Skip to content

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

8.3 KB
Raw Blame

Manage runtime credentials and app-user sessions

Choose the credential pattern first in authentication.md. This guide's tenant coordinator applies to direct API-key authentication. For server-enforced user grants, use VModal.connectWithBackend and the scoped coordinator described in auth_user_backend_mode.md. Do not share a scoped credential source across users or attach it to the tenant-wide rotation flow.

Retrieve credentials through the host's authenticated, trusted service and keep them in memory. Direct VModal API keys identify the tenant principal; Firebase, Clerk, or another host identity system supplies the stable app-user ID. A and B may share one tenant key and auth.me() response. That response never selects their local owner namespace or proves their content permissions. Scoped auth/me instead adds the verified app subject/project/policy/grants and is checked against the envelope before the backend connection becomes ready.

Backend connection lifecycle

final backend = await VModal.connectWithBackend(
  expectedAppUserId: signedInUser.id,
  expectedProjectId: 'framebase',
  loadToken: () async => ScopedTokenEnvelope.fromJson(
    await developerApi.createVmodalSession(),
  ),
);
final library = backend.scope('my_library');
await backend.refresh(); // coalesced renewal, no mutation replay
await backend.close(); // local VModal cleanup; host owns sign-out

The callback verifies current host login through the developer backend on every acquisition and returns only a short-lived VModal-signed token. Parse/identity errors differ from temporary availability failures; see the backend guide and the reference adapter.

Shared HTTP gateway paths check readiness before taking Bearer snapshots. Proactive renewal leeway is capped at half the lifetime. Expiry uses expires_at, and renewal is coalesced. A valid token may continue during a temporary outage; expired or rejected revisions block dispatch. Same-policy renewal preserves session and owner; changed policy/binding requires reconnect.

Observe token-free ready, refreshing, unavailable, expired, invalidated and closed events at the account owner. Call close() at the start of an account transition and discard retired scopes/UI. Backend owner identity includes project/service/tenant/user and excludes bearer, expiry and jti.

The tenant-specific sections below retain their contract. The tenant option retainOnRenewalFailure is not a backend-mode fallback to broader credentials.

Session-bound configuration

final config = SdkConfig(); // gateway mode
final namespace = SessionContext.serviceNamespaceFor(config);
final credentials = TenantCredentialSource(
  serviceNamespace: namespace,
  tenantId: tenantId,
  expectedPrincipal: tenantPrincipal,
  initialKey: runtimeTenantKey,
  renew: () async => TenantCredential(
    serviceNamespace: namespace,
    tenantId: tenantId,
    principal: tenantPrincipal,
    apiKey: await trustedIssuer.currentTenantKey(),
  ),
);
final manager = UserSessionManager(
  config: config,
  credentialSource: credentials,
);

The host's issuer/resolver must authenticate and validate the credential's service/tenant/principal binding. These fields are compared locally; self-reported labels on an arbitrary key are not proof. session.verifyPrincipal(...) can add an auth.me() tenant-principal check. It does not identify the app user or validate that user's mapping. Prefer authoritative integer issuerVersion values when the issuer supports them; when absent, the trusted resolver must return its currently valid key. auth.me() cannot order opaque keys by age.

Coordinate tenant rotation

credentials.renewCredential() shares one normal renewal Future across active matching providers. install(TenantCredential(...)) installs a trusted external replacement. renewCredential(supersede: true) deliberately fences earlier renewal tickets. Accepted revision and request ticket checks reject late results; authoritative issuer versions reject rollback. Commit is atomic within the isolate, updates only live matching providers, and new sessions attach/read the latest revision without an asynchronous gap. Closing A unsubscribes its provider without canceling shared renewal needed by B.

credentials.install(TenantCredential(
  serviceNamespace: namespace,
  tenantId: tenantId,
  principal: tenantPrincipal,
  apiKey: replacementTenantKey,
));

A credential-only replacement preserves sessionId, stable owner/scope keys, app user, mapping, policy, and multipart checkpoint namespace. Tenant, endpoint, or principal changes are rejected in place: build a correctly bound source and fresh sessions. Grant/mapping changes also require invalidation and fresh policy resolution, even when the key or app-user ID stays equal.

By default renewal failure blocks tenant calls, retains no fallback authority, and returns a classified TenantAuthException. It does not log out the host app user or change the active owner. retainOnRenewalFailure: true is available only when the host's authoritative validity policy permits using the prior key. revoke() is an authoritative current-credential revocation and blocks gateway calls; a stale request's 401 cannot revoke a newer accepted revision. Recover the tenant connection through the trusted source rather than falling back to a broader credential. credentials.close() retires the shared coordinator; closing one user session leaves the coordinator available to another.

Request snapshots and recovery

The HTTP layer captures a binding/revision and header snapshot at request construction. Ordinary retries retain that snapshot. Rotation does not rewrite an existing request. New requests read the latest committed credential. Existing calls can finish with the prior key while the service still accepts it; every attempt and delivery remains guarded by its original app-user lease.

An eligible active GET/HEAD read can recover from 401 at most once per logical request by consulting the coordinator and reconstructing fresh headers. It shares a bounded attempt budget with ordinary retries. A second denial returns a tenant-auth error while preserving app-user identity. 403 is never a general refresh trigger. Uploads, index submissions, deletions, and other mutations are never automatically replayed through auth recovery; ambiguous completion remains unknown and requires deliberate reconciliation. Multipart continuation uses only its existing explicit status/part/resume protocol and validated owner checkpoints.

Signed URLs have independent validity and expiry. Rotating or revoking the tenant key does not promise to revoke an already issued storage/media capability. Never attach a replacement bearer to a signed storage request. The session guard still blocks later local signed-upload dispatch and media delivery after logout.

Account changes and the host boundary

Call manager.logout() or manager.openResolvedSession(...) at the start of an identity transition. Invalidation happens before asynchronous resolution or cleanup. Clear old displayed images, playback, navigation/restoration, and histories; check the current view generation before applying asynchronous host state updates. Persisted owner data may remain for a later verified activation, but old runtime handles never become valid again. Local cache reuse requires current policy validation.

The compatible tenant-scoped API still accepts MutableApiKeyProvider:

final provider = MutableApiKeyProvider(runtimeTenantKey);
final project = VModal.configure(
  projectId: 'food_app',
  apiKeyProvider: provider,
);
provider.rotate(replacementTenantKey); // later requests only
provider.close(); // permanently disables reads and rotation
await project.close();

VmodalClient/VModalProject bypass user-session isolation; the host must own their complete cancellation, cache/checkpoint partitioning, and account-switch contract. Never use projectId or tenant identity as proof of app-user identity. Never commit keys, put them in assets, log them, persist them in jobs/archives, or treat compile-time --dart-define values as production credential storage.

See the SDK contract for result provenance, restricted media, local storage fencing, and the shared-key modified-client limitation.