Skip to content

V- Modal AI: Visual Video / Image Search - Flutter Video SDK

7.4 KB
Raw Blame

Developer-backend scoped authentication reference

This separate integration reference leaves 05_framebase_userlogin unchanged. That existing app demonstrates host login with shared-key local isolation. This reference obtains a VModal-issued scoped token through your authenticated developer backend and uses the same guarded SDK session operations.

It is a host integration library, not another login UI or deployable identity provider. Prerequisites are a verified host identity/session, an existing policy store, and a VModal deployment with registered scoped issuance and complete resource enforcement. Use Choose authentication and Backend authentication alongside it.

1. Authenticate and connect

Add this SDK as a local development dependency or pin a verified immutable published revision containing connectWithBackend. The reference pubspec.yaml already points to the sibling SDK checkout.

final owner = BackendSessionOwner();
final connection = await owner.activate(
  appUserId: signedInUser.id,
  projectId: 'framebase',
  loadToken: () async {
    // Uses your CURRENT authenticated backend client; no master key in Flutter.
    final response = await developerApi.post('/vmodal/session', body: {});
    return parseBackendResponse(
      response.statusCode,
      response.decodedJson,
      retryAfter: response.safeRetryAfter,
    );
  },
);

developerApi, signedInUser and its response adapter belong to your host app. Map network/timeouts to BackendAuthFailure.unavailable. JSON decoding or a malformed envelope is invalidResponse; never include raw response bodies or identity tokens in errors. parseBackendResponse demonstrates safe status classification, including identity rejection, policy denial and throttling.

The SDK confirms the candidate through VModal auth/me before returning ready. The owner fences activation results when login changes during acquisition.

2. Discover allowed content, then search

final collections = await connection.session.listCollections();
final library = connection.scope('my_library');
final info = await library.collectionInfo();
final results = await library.search('a cyclist entering the street');
if (results.assets.isNotEmpty) {
  final bytes = await library.imageBytes(results.assets.first);
}

The grant label resolves the backend's exact collection/stream/mode mapping; Flutter constructs no collection name. Index discovery requires indexation and is unavailable until the deployment enforces and enables that action. The initial read-only scoped deployment does not offer upload, metadata, indexation or delete. Those existing SDK APIs remain usable in direct auth.

3. Implement the developer backend handoff

developer_backend/session.mjs exports a small node:http handler. Node 22+ provides the built-in fetch, AbortSignal and native test APIs it uses. It has no npm dependencies. Translate its handoff into your existing server stack if your application uses another language.

Mount it in your existing backend:

import { createVmodalSessionHandler, IdentityRejected, AccessDenied }
  from './developer_backend/session.mjs';

const sessionHandler = createVmodalSessionHandler({
  projectId: serverConfig.vmodalProject,
  vmodalOrigin: serverConfig.vmodalOrigin,
  loadServerKey: async ({ signal }) => secrets.currentRegisteredVmodalKey({ signal }),
  verifyIdentity: async (req, { signal }) => {
    const session = await hostAuth.verifyCurrentRequest(req, { signal });
    if (!session) throw new IdentityRejected();
    return { subject: session.stableSubject };
  },
  resolvePolicy: async (subject, { signal }) => {
    const policy = await policies.forVerifiedSubject(subject, { signal });
    if (!policy?.enabled) throw new AccessDenied();
    return { enabled: true, revision: policy.revision, grants: policy.exactGrants };
  },
});
// Route POST /vmodal/session to sessionHandler(req, res) in your server.

The named configuration, auth, policy and secret objects are mandatory host adapters. No built-in verifier accepts a phone-supplied user ID. A cookie-based host can verify cookies instead of Bearer identity tokens. Do not validate identity by decoding an unsigned JWT or comparing an unverified UID.

The handler accepts only {}; the host determines subject, project and grants. It re-verifies identity and reloads policy for every renewal. Only the registered server credential goes to /api/v1/auth/scoped-token. Issuer redirects are rejected so that credential does not follow another origin. The host identity credential is never forwarded to VModal.

Successful envelopes pass through unchanged after expected identity/project/ policy checks. Responses are not cacheable. Identity rejection is 401, access denial is 403, issuer contract/configuration rejection is 502, temporary issuer failure is 503, and throttling is 429 with bounded Retry-After. Errors never relay issuer bodies or server secrets. Acquisition is bounded by a single timeout, including response decoding, and adapters receive its cancellation signal. The Dart adapter recognizes the safe issuer_contract_rejected code on 502 as invalidResponse; other unclassified gateway 5xx responses are temporary unavailable errors.

This handler requires server configuration/secret injection; it creates no new Flutter environment variables and no server process or deployment. Your backend retains its own configuration conventions and login/session lifecycle.

4. Renewal, transition and cleanup

The SDK coalesces renewal and performs request-time expiry gating. A temporary issuer outage preserves host login and may retain a still-valid scoped token. Failed POST searches are surfaced, and writes are not automatically replayed.

At the start of account switch/logout, clear host UI and call:

await owner.close(); // immediately retires VModal state; host owns sign-out
await hostAuth.signOut();

For another verified account, call activate again. Changed policy/grants also require fresh activation. Widgets retain a session-owned UserScope and must discard it on invalidation. Feature pages do not close a connection shared by other pages. Already issued signed URLs and remote jobs retain their separate lifetime; local close does not promise distributed instant revocation.

5. Run offline reference checks

From the SDK root:

# The normal build gates include this reference's Dart pub_get/format/analyze/test.
# The backend handler has an optional separate Node gate (no npm dependencies).
node --test example/06_userlogin_backend_auth/developer_backend/session_test.mjs
flutter_bin="$(bash install.sh flutter_bin)"
cd example/06_userlogin_backend_auth
"$flutter_bin" pub get
"$flutter_bin" analyze
"$flutter_bin" test

Backend tests exercise verified identity, spoof attempts, denied policy, unchanged envelopes, no master-key return, safe issuer errors, renewal re-verification and timeout, malformed issuer JSON and response-decoding timeout. Dart checks cover callback error classification; the SDK's test/backend_auth_test.dart covers credential/session behavior.

Expected result: all offline checks pass without a live key or identity provider. Tests create temporary local HTTP listeners and close them after each case. No scoped production availability is inferred from fake issuers. Before enabling your integration, run the public-edge acceptance checks in the backend guide.