@opengeni/core 3.0.1 → 3.1.2

package/src/access/index.ts

@@ -6,17 +6,29 @@ import {
   type ExternalIdentity,
 } from "@opengeni/contracts/external-identities";
 import {
+  accessContextHasInbox,
   verifyDelegatedAccessToken,
+  DEVELOPER_SETUP_API_KEY_PRESET,
+  normalizePermission,
+  organizationAccessPresetPermissions,
   type AccountGrant,
   type AccessContext,
   type AccessGrant,
+  type OrganizationApiKeyAccess,
+  OrganizationWorkspaceScope,
+  OPENGENI_USER_ACTIVITY_ACTIVE,
+  OPENGENI_USER_ACTIVITY_HEADER,
   Permission,
   type Workspace,
 } from "@opengeni/contracts";
 import {
   bootstrapWorkspace,
   ensureManagedAccessForUser,
+  getManagedUserProfilesByIds,
   ensureExternalIdentity,
+  ensureExternalWorkspaceMemberOnFirstUse,
+  USER_ISOLATION_WORKSPACE_SOURCE_PREFIX,
+  lockExternalWorkspaceMembershipLifecycle,
   resolveExternalIdentityLink,
   managedPersonalWorkspacePermissions,
   nestedPostgresSqlState,
@@ -31,12 +43,109 @@ import {
 } from "@opengeni/db";
 import type { Context } from "hono";
 import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
 import type { ManagedAuth } from "../managed-auth-type";
-import { getManagedSession } from "../managed-session";
+import {
+  getManagedSession,
+  getNativeAppManagedSession,
+  NATIVE_APP_CREDENTIAL_PREFIX,
+} from "../managed-session";
 import type { ManagedAuthSessionAdapter } from "../managed-auth-session-sets";
+import type { UserPresenceRecorder } from "../user-presence";
+import { serviceInitiatorFromHeaders } from "./service-initiator";
 
 const bearerPrefix = "Bearer ";
 const accessContextByRequest = new WeakMap<Request, Promise<AccessContext | null>>();
+const accessResolvedRequests = new WeakSet<Request>();
+const developerSetupApiKeyContexts = new WeakSet<AccessContext>();
+const developerSetupAuthorizations = new WeakMap<AccessGrantAuthorization, AccessGrant>();
+const developerSetupGrants = new WeakSet<AccessGrant>();
+// Request-local permission semantics. The durable grant carries permissionMode;
+// callers of the existing array API cannot accidentally expand a policy admin.
+const explicitPermissionSets = new WeakSet<readonly Permission[]>();
+function explicitPermissions(permissions: Permission[]): Permission[] {
+  explicitPermissionSets.add(permissions);
+  return permissions;
+}
+
+/** Only canonical authentication can prove setup-key provenance. */
+export function isDeveloperSetupApiKeyContext(context: AccessContext): boolean {
+  return (
+    developerSetupApiKeyContexts.has(context) &&
+    accountScopedApiKeyWorkspaceAuthority(context) !== null
+  );
+}
+
+/** Provenance from canonical raw-key or verified restricted-token authentication. */
+export function isDeveloperSetupAuthorization(
+  authorization: AccessGrantAuthorization | undefined,
+): boolean {
+  return (
+    authorization !== undefined &&
+    developerSetupAuthorizations.get(authorization) === authorization.grant
+  );
+}
+
+/** Exact grant objects resolved under authenticated setup-only provenance. */
+export function isDeveloperSetupGrant(grant: AccessGrant): boolean {
+  return developerSetupGrants.has(grant);
+}
+
+/** Setup-derived credentials cannot carry literal organization or key authority. */
+export function isDeveloperSetupDelegatedPermissionAllowed(permission: Permission): boolean {
+  return (
+    permission !== "secrets:read" &&
+    permission !== "api_keys:manage" &&
+    !accountScopedApiKeyWorkspaceExcludedPermissions.has(permission)
+  );
+}
+
+/** Canonical authentication provenance, including the backing key of asUser. */
+export function requireApiKeyManagementContext(context: AccessContext): void {
+  if (developerSetupApiKeyContexts.has(context)) {
+    throw new HTTPException(403, { message: "Developer setup keys cannot manage API keys" });
+  }
+}
+
+/** Membership is not an escape hatch for minting durable credentials. */
+export function requireApiKeyDelegationContext(
+  context: AccessContext,
+  permissions: Permission[],
+): void {
+  const authority = accountScopedApiKeyWorkspaceAuthority(context);
+  const external = externalActorContexts.get(context);
+  const ceiling = authority ?? external;
+  if (
+    ceiling?.permissionMode === "explicit" &&
+    permissions.some((permission) => !ceiling.permissions.includes(permission))
+  ) {
+    throw new HTTPException(403, {
+      message: "cannot delegate a permission outside the organization key policy",
+    });
+  }
+  if (
+    ceiling?.permissionMode === "explicit" &&
+    permissions.includes("workspace:admin") &&
+    organizationAccessPresetPermissions("full").some(
+      (permission) =>
+        !accountScopedApiKeyWorkspaceExcludedPermissions.has(permission) &&
+        !ceiling.permissions.includes(permission),
+    )
+  ) {
+    throw new HTTPException(403, {
+      message: "cannot delegate a legacy workspace-admin wildcard from a custom policy",
+    });
+  }
+  if (
+    (hasPermission(permissions, "api_keys:manage") ||
+      hasPermission(permissions, "members:manage")) &&
+    developerSetupApiKeyContexts.has(context)
+  ) {
+    throw new HTTPException(403, {
+      message: "Setup credentials cannot delegate API key management",
+    });
+  }
+}
 
 /**
  * Contexts that were authenticated by a verified canonical managed cookie
@@ -58,16 +167,261 @@ const accessContextByRequest = new WeakMap<Request, Promise<AccessContext | null
  * the value the cookie branch produced.
  */
 const canonicalManagedCookieContexts = new WeakSet<AccessContext>();
+/** Downstream legacy credentials cannot encode a partially selected admin. */
+export function requireExplicitPermissionDelegation(
+  grant: Pick<AccessGrant, "permissions" | "permissionMode">,
+  requested: Permission[],
+): void {
+  if (
+    grant.permissionMode === "explicit" &&
+    requested.some((permission) => !grant.permissions.includes(permission))
+  ) {
+    throw new HTTPException(403, {
+      message: "cannot delegate a permission outside the organization key policy",
+    });
+  }
+  if (
+    grant.permissionMode === "explicit" &&
+    requested.includes("workspace:admin") &&
+    organizationAccessPresetPermissions("full").some(
+      (permission) =>
+        !accountScopedApiKeyWorkspaceExcludedPermissions.has(permission) &&
+        !grant.permissions.includes(permission),
+    )
+  ) {
+    throw new HTTPException(403, {
+      message: "cannot delegate a legacy workspace-admin wildcard from a custom policy",
+    });
+  }
+}
 const canonicalLocalHumanContexts = new WeakSet<AccessContext>();
+
+export type DelegatedHumanAuthorization = Readonly<{
+  organizationId: string;
+  /** Exact native person subject, never an external identity or service. */
+  subjectId: string;
+  permissions: Permission[];
+  workspaceScope: OrganizationWorkspaceScope;
+}>;
+
+const delegatedHumanAuthorizationSchema = z.object({
+  organizationId: z.string().uuid(),
+  subjectId: z
+    .string()
+    .max(1024)
+    .regex(/^user:[^\s\u0000-\u001f\u007f]+$/),
+  permissions: z.array(Permission),
+  workspaceScope: OrganizationWorkspaceScope,
+});
+
+const delegatedHumanRequests = new WeakMap<Request, DelegatedHumanAuthorization>();
+const delegatedHumanContexts = new WeakMap<AccessContext, DelegatedHumanAuthorization>();
+const delegatedHumanProfileSchema = z.object({
+  id: z.string(),
+  name: z.string().nullable(),
+  email: z.string(),
+  emailVerified: z.boolean().optional(),
+});
+
+export type VerifiedDelegatedHumanContext = Readonly<{
+  /** Native identity projection only, never a browser/auth session. Absence of
+   * emailVerified means the native lookup did not prove email verification. */
+  user: Readonly<z.infer<typeof delegatedHumanProfileSchema>>;
+  subjectId: string;
+  authorization: DelegatedHumanAuthorization;
+  context: AccessContext;
+}>;
+
+const delegatedHumanProfiles = new WeakMap<AccessContext, VerifiedDelegatedHumanContext["user"]>();
+const verifiedDelegatedHumanAuthorizations = new WeakMap<
+  AccessGrantAuthorization,
+  {
+    proof: DelegatedHumanAuthorization;
+    grant: AccessGrant;
+    accountGrant: AccountGrant;
+  }
+>();
+
+/**
+ * TRUSTED OAUTH VERIFIED DISPATCH ONLY. Before each stamp the in-process caller
+ * must validate the live OAuth grant, revocation, exact native person subject,
+ * organization, permission ceilings and workspace scope. This API does not
+ * verify OAuth and must NEVER be called with headers, metadata, token claims,
+ * a previous request's proof, or other unverified caller input.
+ *
+ * Stamp the exact raw Request that the actions dispatcher will pass to routes,
+ * before any access resolution. Cloning/wrapping a Request does not copy proof.
+ * The resolver reloads the real native person's live access on this request
+ * (and on fresh reauthorization); no session or cached grant is fabricated or
+ * transplanted. This proof never becomes managed-cookie/person-present proof.
+ */
+export function stampDelegatedHumanAuthorization(
+  request: Request,
+  input: DelegatedHumanAuthorization,
+): void {
+  if (delegatedHumanRequests.has(request) || accessResolvedRequests.has(request)) {
+    throw new HTTPException(403, { message: "request access authorization already resolved" });
+  }
+  const parsed = delegatedHumanAuthorizationSchema.safeParse(input);
+  if (!parsed.success) {
+    throw new HTTPException(403, { message: "invalid delegated human authorization" });
+  }
+  const verified = parsed.data;
+  const workspaceScope: DelegatedHumanAuthorization["workspaceScope"] =
+    verified.workspaceScope.kind === "all"
+      ? { kind: "all" }
+      : { kind: "selected", workspaceIds: [...verified.workspaceScope.workspaceIds] };
+  if (workspaceScope.kind === "selected") Object.freeze(workspaceScope.workspaceIds);
+  Object.freeze(workspaceScope);
+  const proof: DelegatedHumanAuthorization = {
+    organizationId: verified.organizationId,
+    subjectId: verified.subjectId,
+    permissions: [...new Set(verified.permissions)],
+    workspaceScope,
+  };
+  Object.freeze(proof.permissions);
+  delegatedHumanRequests.set(request, Object.freeze(proof));
+}
+
+/** Token prefix of personal API keys, which act as the person who made them. */
+export const PERSONAL_API_KEY_TOKEN_PREFIX = "ogp_";
+
+/**
+ * A personal API key acts as its owner. Call once per incoming request, after
+ * any middleware that may rebuild the Request and before access resolution:
+ * an active personal key stamps this exact raw Request with its owner and
+ * access setting, so the request resolves through the same live-access path as
+ * a person's signed-in agent (their current membership, role and workspaces,
+ * capped by the key) and routes treat it as that person. Anything else is left
+ * to the ordinary resolver, which refuses an unknown or revoked key.
+ */
+export async function stampPersonalApiKeyRequest(
+  request: Request,
+  deps: Pick<AccessDeps, "db">,
+): Promise<boolean> {
+  const authorization = request.headers.get("authorization");
+  if (!authorization?.startsWith(`${bearerPrefix}${PERSONAL_API_KEY_TOKEN_PREFIX}`)) return false;
+  if (
+    request.headers.has("x-opengeni-external-actor") ||
+    serviceInitiatorFromHeaders(request.headers)
+  ) {
+    throw new HTTPException(403, {
+      message: "A personal API key acts only as the person who created it.",
+    });
+  }
+  const apiKey = await findActiveApiKeyByHash(
+    deps.db,
+    await sha256Hex(authorization.slice(bearerPrefix.length)),
+  );
+  if (!apiKey || apiKey.credentialKind !== "personal" || !apiKey.ownerSubjectId) return false;
+  stampDelegatedHumanAuthorization(request, {
+    organizationId: apiKey.accountId,
+    subjectId: apiKey.ownerSubjectId,
+    permissions: (apiKey.ownerPermissions ?? []).flatMap((permission) => {
+      const parsed = Permission.safeParse(permission);
+      return parsed.success ? [parsed.data] : [];
+    }),
+    workspaceScope: apiKey.workspaceScope ?? { kind: "all" },
+  });
+  return true;
+}
+
+/** Immutable verified dispatch bounds for this exact raw Request, not a grant. */
+export function verifiedDelegatedHumanAuthorizationForRequest(
+  request: Request,
+): DelegatedHumanAuthorization | null {
+  return delegatedHumanRequests.get(request) ?? null;
+}
+
+/**
+ * Resolve the exact verified OAuth-dispatch person and constrained live native
+ * access for this raw Request. Unstamped requests (even browser cookies) fail
+ * closed; callers must not fall back to a service or subject-shaped identity.
+ * Uses the same request-local native resolution as requireAccessContext.
+ *
+ * No session, session id or managed-cookie proof is created. emailVerified is
+ * forwarded only when the native profile lookup supplies it; missing is not
+ * verified and must never be filled from OAuth claims, headers or metadata.
+ */
+export async function requireVerifiedDelegatedHumanContext(
+  c: Context,
+  deps: AccessDeps,
+): Promise<VerifiedDelegatedHumanContext> {
+  const authorization = verifiedDelegatedHumanAuthorizationForRequest(c.req.raw);
+  if (!authorization) {
+    throw new HTTPException(401, { message: "verified delegated human authorization required" });
+  }
+  const context = await requireAccessContext(c, deps);
+  const user = delegatedHumanProfiles.get(context);
+  if (delegatedHumanContexts.get(context) !== authorization || !user) {
+    throw new HTTPException(403, { message: "delegated native person authority is unavailable" });
+  }
+  return Object.freeze({ user, subjectId: context.subjectId, authorization, context });
+}
+
+/** Exact resolved owning-person authorization; clones and service claims fail.
+ * Supplying the raw Request additionally binds proof to that exact dispatch,
+ * not another request with the same native person and authorization bounds. */
+export function isVerifiedDelegatedHumanAuthorization(
+  authorization: AccessGrantAuthorization,
+  request?: Request,
+): boolean {
+  const verified = verifiedDelegatedHumanAuthorizations.get(authorization);
+  return Boolean(
+    verified &&
+    (request === undefined || verified.proof === delegatedHumanRequests.get(request)) &&
+    authorization.contextIntegrity &&
+    !authorization.canonicalManagedHumanSession &&
+    !authorization.canonicalLocalHumanSession &&
+    authorization.grant === verified.grant &&
+    authorization.accountGrant === verified.accountGrant &&
+    authorization.authenticatedSubjectId === verified.proof.subjectId &&
+    verified.grant.subjectId === verified.proof.subjectId &&
+    verified.grant.accountId === verified.proof.organizationId &&
+    delegatedHumanWorkspaceAllowed(verified.proof, verified.grant.workspaceId),
+  );
+}
+
+function delegatedHumanWorkspaceAllowed(
+  proof: DelegatedHumanAuthorization,
+  workspaceId: string,
+): boolean {
+  return (
+    proof.workspaceScope.kind === "all" || proof.workspaceScope.workspaceIds.includes(workspaceId)
+  );
+}
 const externalActorContexts = new WeakMap<
   AccessContext,
   {
     identity: ExternalIdentity;
     keyId: string;
     permissions: Permission[];
+    workspaceScope: OrganizationWorkspaceScope;
+    permissionMode: "legacy" | "explicit";
     linked?: NonNullable<Awaited<ReturnType<typeof resolveExternalIdentityLink>>>;
+    /**
+     * Plain external mode (no native link, no service-initiator attribution):
+     * the only lane where a missing shared-workspace membership may be created
+     * on first use. See {@link provisionExternalMemberOnFirstUse}.
+     */
+    firstUseMembership: boolean;
   }
 >();
+
+/**
+ * Default permissions for a membership created on an external user's first
+ * request. Keep equal to `CONVERSATION_PERMISSIONS` in
+ * `packages/sdk/src/tenant-workspaces.ts`: conversation use only, no admin.
+ */
+export const EXTERNAL_FIRST_USE_MEMBER_PERMISSIONS: readonly Permission[] = [
+  "workspace:read",
+  "sessions:create",
+  "sessions:read",
+  "sessions:control",
+  "files:upload",
+  "files:read",
+  "mcp_servers:attach",
+];
 function attributionForExternalContext(context: AccessContext): ExternalActorAttribution {
   const external = externalActorContexts.get(context);
   if (!external) throw new Error("Verified external context required");
@@ -90,6 +444,7 @@ const verifiedExternalAuthorizations = new WeakMap<
   {
     grant: AccessGrant;
     workspaceId: string;
+    workspaceSettingsCeiling: boolean;
     identityReference: { externalId: string; source: string };
     attribution: ExternalActorAttribution;
   }
@@ -122,7 +477,7 @@ export function externalActorContinuationForAuthorization(
   return actor && verified ? { actor, identity: { ...verified.identityReference } } : null;
 }
 
-/** Dedicated owning-user proof. External admission never sets the native
+/** Dedicated owning-user proof. External/OAuth admission never sets the native
  * cookie stamp. The resource/session layer still checks the exact owner. */
 export function hasVerifiedOwningUserAuthorization(
   authorization: AccessGrantAuthorization,
@@ -134,12 +489,22 @@ export function hasVerifiedOwningUserAuthorization(
     return false;
   return (
     authorization.canonicalManagedHumanSession ||
-    externalAttributionForAuthorization(authorization, authorization.grant) !== null
+    externalAttributionForAuthorization(authorization, authorization.grant) !== null ||
+    isVerifiedDelegatedHumanAuthorization(authorization)
   );
 }
 const accountScopedApiKeyContexts = new WeakMap<
   AccessContext,
-  Readonly<{ accountId: string; permissions: readonly Permission[] }>
+  Readonly<{
+    accountId: string;
+    permissions: readonly Permission[];
+    workspaceScope: OrganizationWorkspaceScope;
+    permissionMode: "legacy" | "explicit";
+  }>
+>();
+const apiKeyServiceContexts = new WeakMap<
+  AccessContext,
+  Pick<AccessGrant, "serviceInitiator" | "serviceInitiatorContext">
 >();
 const verifiedOrganizationServiceAuthorizations = new WeakMap<
   AccessGrantAuthorization,
@@ -163,6 +528,7 @@ const accountScopedApiKeyAccountPermissions = new Set<Permission>([
   "billing:read",
   "billing:manage",
   "api_keys:manage",
+  "usage_allowances:manage",
 ]);
 const accountScopedApiKeyWorkspaceExcludedPermissions = new Set<Permission>([
   "account:read",
@@ -170,13 +536,23 @@ const accountScopedApiKeyWorkspaceExcludedPermissions = new Set<Permission>([
   "workspace:create",
   "billing:read",
   "billing:manage",
+  "usage_allowances:manage",
 ]);
 
 export type AccountScopedApiKeyWorkspaceAuthority = Readonly<{
   accountId: string;
   permissions: Permission[];
+  workspaceScope: OrganizationWorkspaceScope;
+  permissionMode: "legacy" | "explicit";
 }>;
 
+export function organizationWorkspaceInScope(
+  scope: OrganizationWorkspaceScope,
+  workspaceId: string,
+): boolean {
+  return scope.kind === "all" || scope.workspaceIds.includes(workspaceId.toLowerCase());
+}
+
 /**
  * Return account-scoped API-key workspace authority only for the exact
  * AccessContext object stamped by successful API-key authentication. Subject
@@ -200,10 +576,27 @@ export function accountScopedApiKeyWorkspaceAuthority(
   }
   return {
     accountId: authority.accountId,
-    permissions: [...authority.permissions],
+    permissions:
+      authority.permissionMode === "explicit"
+        ? explicitPermissions([...authority.permissions])
+        : [...authority.permissions],
+    workspaceScope: authority.workspaceScope,
+    permissionMode: authority.permissionMode,
   };
 }
 
+/** Classify stored scopes without changing the legacy full/read permission sets. */
+export function organizationApiKeyAccess(permissions: Permission[]): OrganizationApiKeyAccess {
+  if (
+    permissions.length === DEVELOPER_SETUP_API_KEY_PRESET.permissions.length &&
+    DEVELOPER_SETUP_API_KEY_PRESET.permissions.every((permission) =>
+      permissions.includes(permission),
+    )
+  )
+    return "developer_setup";
+  return permissions.includes("workspace:admin") ? "full" : "read";
+}
+
 /**
  * Opaque, request-local proof that the canonical access resolver authorized the
  * exact account administrator named by the stamp. The random id is audit and
@@ -222,6 +615,8 @@ export type AccessDeps = {
   settings: Settings;
   managedAuth?: ManagedAuth | null;
   managedAuthSessionAdapter?: ManagedAuthSessionAdapter | null;
+  /** Analytics only: notes canonical managed-cookie activity, never authority. */
+  userPresence?: UserPresenceRecorder | null;
 };
 
 /** null means this is not an authenticated external lane; [] means that lane
@@ -245,10 +640,16 @@ export async function listExternalActorWorkspaces(
   const personal = await withAccountRls(deps.db, actor.identity.accountId, (tx) =>
     requireWorkspace(tx, actor.linked?.personalWorkspaceId ?? actor.identity.personalWorkspaceId),
   );
-  if (personal.accountId === actor.identity.accountId && personal.kind === "personal")
+  if (
+    personal.accountId === actor.identity.accountId &&
+    personal.kind === "personal" &&
+    actor.permissionMode === "legacy" &&
+    organizationWorkspaceInScope(actor.workspaceScope, personal.id)
+  )
     authorized.push(personal);
   for (const workspace of candidates) {
     if (workspace.accountId !== actor.identity.accountId || workspace.kind !== "shared") continue;
+    if (!organizationWorkspaceInScope(actor.workspaceScope, workspace.id)) continue;
     const grant = await withWorkspaceSubjectRls(deps.db, workspace.id, context.subjectId, (tx) =>
       getWorkspaceGrant(tx, context.subjectId, workspace.id),
     );
@@ -305,8 +706,9 @@ export type AccessGrantAuthorization = {
   contextIntegrity: boolean;
   /**
    * Did this request authenticate as the canonical managed-cookie (Better Auth)
-   * session that OWNS this grant's subject? The single input to the owner-only
-   * managed personal-workspace exception; see `isCanonicalManagedHumanSession`.
+   * session that OWNS this grant's subject? Cookie/person-present ceremonies
+   * retain this strict gate; owning-user boundaries use
+   * `hasVerifiedOwningUserAuthorization` instead.
    * False for every bearer, API-key, delegated, service, local, and configured
    * principal, and for any future path that does not verify a cookie.
    */
@@ -348,6 +750,10 @@ export function accessGrantAuthorizationFromContext(
     canonicalLocalHumanSession: isCanonicalLocalHumanSession(context, grant),
   };
   resolvedAccessGrantAuthorizations.add(authorization);
+  if (contextIntegrity && developerSetupApiKeyContexts.has(context)) {
+    developerSetupAuthorizations.set(authorization, grant);
+    developerSetupGrants.add(grant);
+  }
   if (
     contextIntegrity &&
     accountScopedApiKeyWorkspaceAuthority(context)?.accountId === grant.accountId &&
@@ -360,6 +766,9 @@ export function accessGrantAuthorizationFromContext(
     verifiedExternalAuthorizations.set(authorization, {
       grant,
       workspaceId: grant.workspaceId,
+      workspaceSettingsCeiling:
+        hasPermission(external.permissions, "workspace:admin") &&
+        (!external.linked || hasPermission(external.linked.link.permissions, "workspace:admin")),
       identityReference: {
         externalId: external.identity.externalId,
         source: external.identity.source,
@@ -367,6 +776,27 @@ export function accessGrantAuthorizationFromContext(
       attribution: attributionForExternalContext(context),
     });
   }
+  const delegatedHuman = delegatedHumanContexts.get(context);
+  if (
+    delegatedHuman &&
+    contextIntegrity &&
+    context.workspaceGrants.includes(grant) &&
+    grant.accountId === delegatedHuman.organizationId &&
+    grant.subjectId === delegatedHuman.subjectId &&
+    grant.principalKind === "human_session" &&
+    !grant.serviceInitiator &&
+    !grant.serviceInitiatorContext &&
+    delegatedHumanWorkspaceAllowed(delegatedHuman, grant.workspaceId)
+  ) {
+    verifiedDelegatedHumanAuthorizations.set(authorization, {
+      proof: delegatedHuman,
+      grant,
+      accountGrant: matchingAccountGrants[0]!,
+    });
+    // Keep the exact proof-bearing value immutable: changing a cookie flag,
+    // subject or grant in place must not manufacture browser authentication.
+    Object.freeze(authorization);
+  }
   return authorization;
 }
 
@@ -464,13 +894,19 @@ export async function requireAccessGrantAuthorization(
   permission?: Permission,
 ): Promise<AccessGrantAuthorization> {
   const context = await requireAccessContext(c, deps);
-  return await accessGrantAuthorization(context, deps, workspaceId, permission);
+  // Request entry only: a fresh re-check of a live connection never re-creates
+  // a membership that was removed while the connection was open.
+  return await accessGrantAuthorization(context, deps, workspaceId, permission, {
+    firstUseMembership: true,
+  });
 }
 
 /**
  * Settings administration is narrower than workspace administration. The
- * canonical managed-cookie owner may configure their Personal workspace, but
+ * verified owning user may configure their Personal workspace, but
  * never acquires the admin wildcard (and its membership/delegation powers).
+ * Delegated owners also need workspace:admin in their verified dispatch/key
+ * ceiling: a read-only delegation cannot turn ownership into a settings write.
  * Only use this boundary for workspace configuration, not access management.
  */
 export async function requireWorkspaceSettingsGrant(
@@ -481,8 +917,15 @@ export async function requireWorkspaceSettingsGrant(
   const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
   const grant = requireResolvedAccessGrantAuthorization(authorization, workspaceId);
   if (hasPermission(grant.permissions, "workspace:admin")) return grant;
+  const delegatedHuman = verifiedDelegatedHumanAuthorizations.get(authorization);
+  const ownerSettingsCeiling =
+    authorization.canonicalManagedHumanSession ||
+    verifiedExternalAuthorizations.get(authorization)?.workspaceSettingsCeiling === true ||
+    (delegatedHuman !== undefined && delegatedHuman.proof.permissions.includes("workspace:admin"));
   if (
-    authorization.canonicalManagedHumanSession &&
+    hasVerifiedOwningUserAuthorization(authorization) &&
+    ownerSettingsCeiling &&
+    hasPermission(grant.permissions, "workspace:read") &&
     (await resolveNamedManagedPersonalWorkspaceGrant(deps.db, {
       accountId: grant.accountId,
       workspaceId,
@@ -496,29 +939,183 @@ export async function requireWorkspaceSettingsGrant(
   });
 }
 
+/**
+ * Authority for a shared workspace's own Members surface (list, candidates,
+ * add, change, remove). A holder of the requested workspace permission keeps
+ * the ordinary grant. Otherwise an active organization owner or administrator,
+ * authenticated by the canonical managed cookie, manages any shared workspace
+ * in their organization exactly as through the organization control plane,
+ * with or without an operational membership row there. Every other principal
+ * (API keys, delegated bearers, agents, services, local/configured access)
+ * and every Personal workspace keeps the original refusal. The database
+ * functions re-derive the organization role under the organization fence.
+ */
+export async function requireWorkspaceMemberManagementAuthority(
+  c: Context,
+  deps: AccessDeps,
+  workspaceId: string,
+  permission: "members:manage" | "workspace:read",
+): Promise<{ grant: AccessGrant; organizationAdministrator: boolean }> {
+  try {
+    return {
+      grant: await requireAccessGrant(c, deps, workspaceId, permission),
+      organizationAdministrator: false,
+    };
+  } catch (error) {
+    if (!(error instanceof HTTPException) || error.status !== 403) throw error;
+    const context = await requireAccessContext(c, deps);
+    if (!canonicalManagedCookieContexts.has(context) || !context.subjectId.startsWith("user:")) {
+      throw error;
+    }
+    const workspace = await requireWorkspace(deps.db, workspaceId).catch(() => null);
+    if (!workspace || workspace.kind !== "shared") throw error;
+    const organizationRole = context.accountGrants.find(
+      (candidate) =>
+        candidate.accountId === workspace.accountId && candidate.subjectId === context.subjectId,
+    )?.role;
+    if (organizationRole !== "owner" && organizationRole !== "admin") throw error;
+    return {
+      grant: {
+        workspaceId,
+        accountId: workspace.accountId,
+        subjectId: context.subjectId,
+        ...(context.subjectLabel ? { subjectLabel: context.subjectLabel } : {}),
+        principalKind: "human_session",
+        permissions: ["workspace:read", "members:manage"],
+      },
+      organizationAdministrator: true,
+    };
+  }
+}
+
+/**
+ * Automatic membership for an organization key acting as an external user
+ * (`asUser`): the first request to a shared workspace in the key's own
+ * organization creates the user's missing membership with
+ * {@link EXTERNAL_FIRST_USE_MEMBER_PERMISSIONS}, then the request continues.
+ * It is exactly the authority of explicit `addExternalWorkspaceMember`: the
+ * calling key must hold `members:manage` (or legacy `workspace:admin`) plus
+ * every default permission, with the workspace in its scope, re-checked live
+ * under the organization membership fence together with the identity's own
+ * active status. Never for linked native identities, service-initiator
+ * requests, or any non-key principal (agent attempts, delegated/bearer user
+ * tokens, browser sessions), which never reach the external lane; never for
+ * Personal or SDK per-user workspaces; never when the request needs a
+ * permission outside the defaults. Never changes an existing membership.
+ * Returns true only when a membership now exists; any refusal leaves the
+ * ordinary 403 in place.
+ */
+async function provisionExternalMemberOnFirstUse(
+  deps: AccessDeps,
+  context: AccessContext,
+  external: NonNullable<ReturnType<typeof externalActorContexts.get>>,
+  workspaceId: string,
+  permission: Permission | undefined,
+): Promise<boolean> {
+  if (
+    !external.firstUseMembership ||
+    external.linked ||
+    // A request that would 403 on its own permission anyway creates nothing.
+    (permission !== undefined && !EXTERNAL_FIRST_USE_MEMBER_PERMISSIONS.includes(permission)) ||
+    context.subjectId !== external.identity.subjectId ||
+    !hasPermission(external.permissions, "members:manage", external.permissionMode) ||
+    EXTERNAL_FIRST_USE_MEMBER_PERMISSIONS.some(
+      (required) => !hasPermission(external.permissions, required, external.permissionMode),
+    )
+  )
+    return false;
+  const workspace = await requireWorkspace(deps.db, workspaceId).catch(() => null);
+  if (
+    !workspace ||
+    workspace.kind !== "shared" ||
+    workspace.accountId !== external.identity.accountId ||
+    // SDK per-user workspaces stay single-user: the SDK adds their owner.
+    workspace.externalSource?.startsWith(USER_ISOLATION_WORKSPACE_SOURCE_PREFIX)
+  )
+    return false;
+  try {
+    await ensureExternalWorkspaceMemberOnFirstUse(
+      deps.db,
+      {
+        organizationId: external.identity.accountId,
+        workspaceId,
+        actorSubjectId: `api_key:${external.keyId}`,
+      },
+      {
+        subjectId: external.identity.subjectId,
+        identity: { source: external.identity.source, externalId: external.identity.externalId },
+        permissions: EXTERNAL_FIRST_USE_MEMBER_PERMISSIONS,
+      },
+    );
+    return true;
+  } catch (error) {
+    // A changed/revoked key, narrowed policy or workspace scope keeps the
+    // ordinary denial. Anything else is an infrastructure failure.
+    if (
+      (error as { code?: unknown } | null)?.code === "42501" ||
+      nestedPostgresSqlState(error) === "42501"
+    )
+      return false;
+    throw error;
+  }
+}
+
 async function accessGrantAuthorization(
   context: AccessContext,
   deps: AccessDeps,
   workspaceId: string,
   permission?: Permission,
+  options: { firstUseMembership?: boolean } = {},
 ): Promise<AccessGrantAuthorization> {
+  // No named-subject or organization-key fallback may widen verified OAuth
+  // bounds. These grants came from this resolution's live native access only.
+  if (delegatedHumanContexts.has(context)) {
+    const grant = context.workspaceGrants.find(
+      (candidate) => candidate.workspaceId === workspaceId,
+    );
+    if (!grant)
+      throw new HTTPException(403, { message: "delegated human workspace access denied" });
+    if (permission) requirePermission(grant, permission);
+    return accessGrantAuthorizationFromContext(context, grant);
+  }
   const external = externalActorContexts.get(context);
   if (external) {
-    const grant: AccessGrant | null =
+    if (!organizationWorkspaceInScope(external.workspaceScope, workspaceId)) {
+      throw new HTTPException(403, { message: "workspace is outside organization key scope" });
+    }
+    if (external.permissionMode === "explicit") {
+      const workspace = await requireWorkspace(deps.db, workspaceId);
+      if (workspace.kind !== "shared" || workspace.accountId !== external.identity.accountId)
+        throw new HTTPException(403, {
+          message: "organization policy requires a shared workspace",
+        });
+    }
+    const personal =
       workspaceId ===
-      (external.linked?.personalWorkspaceId ?? external.identity.personalWorkspaceId)
-        ? {
-            accountId: external.identity.accountId,
-            workspaceId,
-            subjectId: context.subjectId,
-            principalKind: "human_session",
-            permissions: [...managedPersonalWorkspacePermissions],
-          }
-        : await withWorkspaceSubjectRls(deps.db, workspaceId, context.subjectId, (tx) =>
-            getWorkspaceGrant(tx, context.subjectId, workspaceId, {
-              principalKind: "human_session",
-            }),
-          );
+      (external.linked?.personalWorkspaceId ?? external.identity.personalWorkspaceId);
+    const membershipGrant = () =>
+      withWorkspaceSubjectRls(deps.db, workspaceId, context.subjectId, (tx) =>
+        getWorkspaceGrant(tx, context.subjectId, workspaceId, {
+          principalKind: "human_session",
+        }),
+      );
+    let grant: AccessGrant | null = personal
+      ? {
+          accountId: external.identity.accountId,
+          workspaceId,
+          subjectId: context.subjectId,
+          principalKind: "human_session",
+          permissions: [...managedPersonalWorkspacePermissions],
+        }
+      : await membershipGrant();
+    if (
+      !grant &&
+      !personal &&
+      options.firstUseMembership === true &&
+      (await provisionExternalMemberOnFirstUse(deps, context, external, workspaceId, permission))
+    ) {
+      grant = await membershipGrant();
+    }
     if (!grant || grant.accountId !== external.identity.accountId) {
       throw new HTTPException(403, { message: "external workspace access denied" });
     }
@@ -531,6 +1128,10 @@ async function accessGrantAuthorization(
         hasPermission(external.permissions, value) &&
         (!external.linked || hasPermission(external.linked.link.permissions, value)),
     );
+    if (external.permissionMode === "explicit") {
+      grant.permissionMode = "explicit";
+      explicitPermissions(grant.permissions);
+    }
     grant.metadata = {
       ...grant.metadata,
       externalActor: attributionForExternalContext(context),
@@ -538,6 +1139,30 @@ async function accessGrantAuthorization(
     if (permission) requirePermission(grant, permission);
     return accessGrantAuthorizationFromContext(context, grant);
   }
+  const organizationKey = accountScopedApiKeyWorkspaceAuthority(context);
+  if (organizationKey) {
+    const workspace = await requireWorkspace(deps.db, workspaceId).catch(() => null);
+    if (!workspace) throw new HTTPException(404, { message: "workspace not found" });
+    if (
+      workspace.accountId !== organizationKey.accountId ||
+      workspace.kind !== "shared" ||
+      !organizationWorkspaceInScope(organizationKey.workspaceScope, workspace.id)
+    ) {
+      throw new HTTPException(403, { message: "workspace is outside organization key scope" });
+    }
+    const grant: AccessGrant = {
+      accountId: workspace.accountId,
+      workspaceId,
+      subjectId: context.subjectId,
+      ...(context.subjectLabel ? { subjectLabel: context.subjectLabel } : {}),
+      principalKind: "api_key",
+      permissions: organizationKey.permissions,
+      permissionMode: organizationKey.permissionMode,
+      ...apiKeyServiceContexts.get(context),
+    };
+    requirePermission(grant, permission ?? "workspace:read");
+    return accessGrantAuthorizationFromContext(context, grant);
+  }
   const principalKind = hostedHumanSessionPrincipalKind(context);
   let grant =
     context.workspaceGrants.find((candidate) => candidate.workspaceId === workspaceId) ??
@@ -547,6 +1172,28 @@ async function accessGrantAuthorization(
       workspaceId,
       principalKind ? { principalKind } : undefined,
     ));
+  if (grant && isDeveloperSetupApiKeyContext(context)) {
+    const authority = accountScopedApiKeyWorkspaceAuthority(context);
+    const workspace = await requireWorkspace(deps.db, workspaceId);
+    if (!authority || workspace.accountId !== authority.accountId || workspace.kind !== "shared") {
+      throw new HTTPException(403, {
+        message: "Developer setup requires a shared organization workspace",
+      });
+    }
+    // A persisted creator/membership grant cannot widen the authenticated key
+    // ceiling, including literal secret reads and inherited session authority.
+    const storedPermissions = grant.permissions;
+    grant = {
+      ...grant,
+      permissions: Permission.options.filter(
+        (value) =>
+          value !== "api_keys:manage" &&
+          !accountScopedApiKeyWorkspaceExcludedPermissions.has(value) &&
+          hasPermission(storedPermissions, value) &&
+          hasPermission(authority.permissions, value),
+      ),
+    };
+  }
   if (!grant) {
     const workspace = await requireWorkspace(deps.db, workspaceId).catch(() => null);
     if (!workspace) {
@@ -567,6 +1214,7 @@ async function accessGrantAuthorization(
         ...(context.subjectLabel ? { subjectLabel: context.subjectLabel } : {}),
         permissions: authority.permissions,
         principalKind: "api_key",
+        ...apiKeyServiceContexts.get(context),
       };
     } else {
       throw new HTTPException(403, { message: "workspace access denied" });
@@ -579,7 +1227,7 @@ async function accessGrantAuthorization(
 }
 
 /**
- * May this grant use the owner-only managed personal-workspace exception?
+ * Did the managed cookie authenticate this exact native person?
  *
  * A managed human's personal workspace carries no `workspace_memberships` row,
  * so seams that fence on one must consult the
@@ -615,6 +1263,30 @@ function isCanonicalManagedHumanSession(context: AccessContext, grant: AccessGra
   );
 }
 
+/**
+ * The subject whose inbox this request may read, or null when it has none.
+ * A signed-in person (`user:`, no key) requires verified managed-human
+ * provenance, including approved native app credentials. The local
+ * install's human qualifies only when the in-process local bootstrap produced
+ * this context (so a delegated bearer naming `dev` cannot borrow it), with the
+ * human-session, non-delegated, non-service, keyless shape of
+ * {@link accessContextHasInbox}. An agent acting as a person (verified
+ * in-process dispatch) reads that person's inbox within its organization and
+ * workspaces: the inbox routes check each item's workspace on this context.
+ */
+export function inboxSubjectForContext(context: AccessContext): string | null {
+  if (!accessContextHasInbox(context)) return null;
+  if (context.subjectId.startsWith("user:")) {
+    return canonicalManagedCookieContexts.has(context) || delegatedHumanContexts.has(context)
+      ? context.subjectId
+      : null;
+  }
+  return canonicalLocalHumanContexts.has(context) &&
+    context.workspaceGrants.every((grant) => isCanonicalLocalHumanSession(context, grant))
+    ? context.subjectId
+    : null;
+}
+
 function isCanonicalLocalHumanSession(context: AccessContext, grant: AccessGrant): boolean {
   return (
     canonicalLocalHumanContexts.has(context) &&
@@ -642,6 +1314,7 @@ function hostedHumanSessionPrincipalKind(context: AccessContext): "human_session
 }
 
 export function requirePermission(grant: AccessGrant, permission: Permission): void {
+  if (grant.permissionMode === "explicit") explicitPermissions(grant.permissions);
   if (!hasPermission(grant.permissions, permission)) {
     if (permission === "variable-sets:use") {
       throw new HTTPException(403, {
@@ -673,23 +1346,63 @@ export function requireLiteralPermission(grant: AccessGrant, permission: Permiss
   }
 }
 
-export function hasLiteralPermission(permissions: Permission[], permission: Permission): boolean {
+export function hasLiteralPermission(
+  permissions: readonly Permission[],
+  permission: Permission,
+): boolean {
   if (!Array.isArray(permissions)) return false;
   return permissions.includes(permission);
 }
 
-export function hasPermission(permissions: Permission[], permission: Permission): boolean {
+export function hasPermission(
+  permissions: readonly Permission[],
+  permission: Permission,
+  permissionMode?: AccessGrant["permissionMode"],
+): boolean {
   if (!Array.isArray(permissions)) return false;
   if (permission === "secrets:read") {
     return permissions.includes("secrets:read");
   }
+  const granted = permissions.includes(permission) || grantsSecretAlias(permissions, permission);
+  if (permissionMode === "explicit" || explicitPermissionSets.has(permissions)) return granted;
   // Variable-set metadata, plaintext read, write/rotation, attachment, and
   // runtime use are independent capabilities. Deprecated broad permissions
   // remain parseable but do not imply any of the exact permissions.
-  return permissions.includes(permission) || permissions.includes("workspace:admin");
+  return granted || permissions.includes("workspace:admin");
+}
+
+/**
+ * Stored roles and API keys keep their legacy variable-set names (Q-16): a
+ * canonical `secrets:*` requirement is met by any granted name that aliases to
+ * it. Legacy requirements (the variable-set routes, until they are removed)
+ * keep their exact meaning. `secrets:read` is never aliased.
+ */
+function grantsSecretAlias(permissions: readonly Permission[], permission: Permission): boolean {
+  if (normalizePermission(permission) !== permission) return false;
+  return permissions.some(
+    (granted) => granted !== permission && normalizePermission(granted) === permission,
+  );
 }
 
 async function resolveAccessContext(c: Context, deps: AccessDeps): Promise<AccessContext | null> {
+  accessResolvedRequests.add(c.req.raw);
+  const delegatedHuman = verifiedDelegatedHumanAuthorizationForRequest(c.req.raw);
+  if (delegatedHuman) return resolveDelegatedHumanAccessContext(deps, delegatedHuman);
+  const service = serviceInitiatorFromHeaders(c.req.raw.headers);
+  if (service) {
+    if (deps.settings.productAccessMode === "local") {
+      throw new HTTPException(422, {
+        message: "service initiator headers require an organization or workspace API key",
+      });
+    }
+    const context = await apiKeyAccessContext(c, deps, deps.settings.productAccessMode);
+    if (!context) {
+      throw new HTTPException(422, {
+        message: "service initiator headers require an organization or workspace API key",
+      });
+    }
+    return context;
+  }
   if (c.req.header("x-opengeni-external-actor") !== undefined) {
     if (deps.settings.productAccessMode === "local") {
       throw new HTTPException(401, {
@@ -743,6 +1456,24 @@ async function resolveAccessContext(c: Context, deps: AccessDeps): Promise<Acces
 
   const bearer = bearerToken(c);
   if (bearer) {
+    if (bearer.startsWith(NATIVE_APP_CREDENTIAL_PREFIX)) {
+      // A native app account: the person approved this device from a signed-in
+      // browser, so it carries the same human authority as that browser.
+      if (!deps.managedAuth) return null;
+      const session = await getNativeAppManagedSession(deps.managedAuth, bearer, deps.db);
+      if (!session?.user) return null;
+      const context = await ensureManagedAccessForUser(deps.db, {
+        userId: session.user.id,
+        email: session.user.email,
+        name: session.user.name,
+        emailVerified: session.user.emailVerified,
+        provisionFallbackOrganization: false,
+        bindPendingInvitations: false,
+      });
+      canonicalManagedCookieContexts.add(context);
+      recordUserPresence(c, deps, context.subjectId);
+      return context;
+    }
     const delegated = await delegatedAccessContext(c, deps, "managed", bearer);
     if (delegated) {
       return delegated;
@@ -773,6 +1504,7 @@ async function resolveAccessContext(c: Context, deps: AccessDeps): Promise<Acces
         bindPendingInvitations: false,
       });
       canonicalManagedCookieContexts.add(context);
+      recordUserPresence(c, deps, context.subjectId);
       return context;
     }
   }
@@ -780,6 +1512,124 @@ async function resolveAccessContext(c: Context, deps: AccessDeps): Promise<Acces
   return null;
 }
 
+async function resolveDelegatedHumanAccessContext(
+  deps: AccessDeps,
+  proof: DelegatedHumanAuthorization,
+): Promise<AccessContext> {
+  if (deps.settings.productAccessMode === "local") {
+    throw new HTTPException(403, {
+      message: "delegated humans require native organization access",
+    });
+  }
+  const userId = proof.subjectId.slice("user:".length);
+  const profiles = await getManagedUserProfilesByIds(deps.db, [userId]);
+  const parsedProfile = delegatedHumanProfileSchema.safeParse(
+    profiles.length === 1 && profiles[0]?.id === userId ? profiles[0] : null,
+  );
+  if (!parsedProfile.success)
+    throw new HTTPException(403, { message: "delegated native person is unavailable" });
+  const profile = parsedProfile.data;
+  const live = await ensureManagedAccessForUser(deps.db, {
+    userId: profile.id,
+    email: profile.email,
+    name: profile.name ?? "",
+    provisionFallbackOrganization: false,
+    bindPendingInvitations: false,
+  });
+  const accounts = live.accountGrants.filter((grant) => grant.accountId === proof.organizationId);
+  if (
+    live.mode !== "managed" ||
+    live.subjectId !== proof.subjectId ||
+    accounts.length !== 1 ||
+    live.accountGrants.some((grant) => grant.subjectId !== proof.subjectId) ||
+    live.workspaceGrants.some(
+      (grant) =>
+        grant.subjectId !== proof.subjectId ||
+        grant.principalKind !== "human_session" ||
+        grant.metadata?.delegated === true ||
+        grant.serviceInitiator ||
+        grant.serviceInitiatorContext,
+    )
+  ) {
+    throw new HTTPException(403, { message: "delegated native person authority is unavailable" });
+  }
+  const verifiedPermissions = [...proof.permissions];
+  // The person's own role expands as usual; the connection's access setting is
+  // literal, and so is the result: workspace:admin in a Custom setting is never
+  // a wildcard for the permissions the person left out.
+  const intersectWorkspacePermissions = (permissions: Permission[]) =>
+    explicitPermissions(
+      Permission.options.filter(
+        (permission) =>
+          hasPermission(permissions, permission) &&
+          hasPermission(verifiedPermissions, permission, "explicit"),
+      ),
+    );
+  const accountGrant: AccountGrant = {
+    ...accounts[0]!,
+    // Organization/billing authority must be literal on BOTH sides, and so is
+    // the result: a workspace:admin entry here never reads as account:admin or
+    // billing to a later permission check.
+    permissions: explicitPermissions(
+      Permission.options.filter(
+        (permission) =>
+          hasLiteralPermission(accounts[0]!.permissions, permission) &&
+          hasLiteralPermission(verifiedPermissions, permission),
+      ),
+    ),
+  };
+  const workspaceGrants = live.workspaceGrants
+    .filter(
+      (grant) =>
+        grant.accountId === proof.organizationId &&
+        delegatedHumanWorkspaceAllowed(proof, grant.workspaceId),
+    )
+    .map((grant) => ({
+      ...grant,
+      permissions: intersectWorkspacePermissions(grant.permissions),
+      permissionMode: "explicit" as const,
+    }));
+  // Proof-bearing authority cannot be changed in place and then reused as if
+  // the resolver had authenticated a different subject, scope or ceiling.
+  for (const grant of [accountGrant, ...workspaceGrants]) {
+    Object.freeze(grant.permissions);
+    Object.freeze(grant);
+  }
+  const context: AccessContext = {
+    mode: "managed",
+    subjectId: proof.subjectId,
+    ...(live.subjectLabel ? { subjectLabel: live.subjectLabel } : {}),
+    accountGrants: [accountGrant],
+    workspaceGrants,
+    defaultAccountId: proof.organizationId,
+    defaultWorkspaceId:
+      workspaceGrants.find((grant) => grant.workspaceId === live.defaultWorkspaceId)?.workspaceId ??
+      workspaceGrants[0]?.workspaceId ??
+      null,
+  };
+  Object.freeze(context.accountGrants);
+  Object.freeze(context.workspaceGrants);
+  Object.freeze(context);
+  delegatedHumanContexts.set(context, proof);
+  delegatedHumanProfiles.set(context, Object.freeze(profile));
+  return context;
+}
+
+/**
+ * Presence counts people, so only the verified managed browser-session branch
+ * reports it, and only for a request the console marked as human activity (a
+ * visible tab with recent interaction). Each request counts once: an SSE
+ * stream's periodic reauthorization reuses its original request.
+ */
+const presenceRecordedRequests = new WeakSet<Request>();
+function recordUserPresence(c: Context, deps: AccessDeps, subjectId: string): void {
+  if (!deps.userPresence) return;
+  if (c.req.header(OPENGENI_USER_ACTIVITY_HEADER) !== OPENGENI_USER_ACTIVITY_ACTIVE) return;
+  if (presenceRecordedRequests.has(c.req.raw)) return;
+  presenceRecordedRequests.add(c.req.raw);
+  deps.userPresence.touch(subjectId);
+}
+
 async function apiKeyAccessContext(
   c: Context,
   deps: AccessDeps,
@@ -793,7 +1643,23 @@ async function apiKeyAccessContext(
   if (!apiKey) {
     return null;
   }
+  // Verified at request entry (stampPersonalApiKeyRequest) and resolved as
+  // its owner; reaching here means that step did not run. Never fall back to
+  // a key-shaped principal.
+  if (apiKey.credentialKind === "personal") {
+    throw new HTTPException(401, { message: "personal API key could not be verified" });
+  }
   const externalHeader = c.req.header("x-opengeni-external-actor");
+  const service = serviceInitiatorFromHeaders(c.req.raw.headers);
+  if (
+    service &&
+    apiKey.credentialKind !== "organization" &&
+    apiKey.credentialKind !== "workspace"
+  ) {
+    throw new HTTPException(422, {
+      message: "service initiator headers require an organization or workspace API key",
+    });
+  }
   if (externalHeader !== undefined) {
     if (apiKey.workspaceId !== null || apiKey.credentialKind !== "organization") {
       throw new HTTPException(403, { message: "external actors require an organization key" });
@@ -807,9 +1673,15 @@ async function apiKeyAccessContext(
     }
     let identity: ExternalIdentity;
     try {
-      identity = await ensureExternalIdentity(deps.db, {
-        accountId: apiKey.accountId,
-        ...selection.identity,
+      identity = await withAccountRls(deps.db, apiKey.accountId, async (tx) => {
+        // Provisioning locks the live membership after its identity lock.
+        // Claim the lifecycle prefix first so a membership-fenced session
+        // writer can recheck that identity without a lock inversion.
+        await lockExternalWorkspaceMembershipLifecycle(tx, apiKey.accountId);
+        return await ensureExternalIdentity(tx, {
+          accountId: apiKey.accountId,
+          ...selection.identity,
+        });
       });
     } catch (error) {
       if (nestedPostgresSqlState(error) === "42501") {
@@ -841,9 +1713,18 @@ async function apiKeyAccessContext(
     externalActorContexts.set(context, {
       identity,
       keyId: apiKey.id,
-      permissions: [...apiKey.permissions],
+      permissions:
+        apiKey.permissionMode === "explicit"
+          ? explicitPermissions([...apiKey.permissions])
+          : [...apiKey.permissions],
+      workspaceScope: apiKey.workspaceScope ?? { kind: "all" },
+      permissionMode: apiKey.permissionMode ?? "legacy",
       ...(linked ? { linked } : {}),
+      firstUseMembership: selection.mode !== "linked_native" && !linked && !service,
     });
+    if (organizationApiKeyAccess(apiKey.permissions) === "developer_setup") {
+      developerSetupApiKeyContexts.add(context);
+    }
     return context;
   }
   const subjectId = `api_key:${apiKey.id}`;
@@ -854,7 +1735,7 @@ async function apiKeyAccessContext(
     : apiKey.permissions.filter((permission) =>
         accountScopedApiKeyAccountPermissions.has(permission),
       );
-  const context = {
+  const context: AccessContext = {
     mode,
     subjectId,
     subjectLabel: apiKey.name,
@@ -875,17 +1756,27 @@ async function apiKeyAccessContext(
             subjectLabel: apiKey.name,
             permissions: apiKey.permissions,
             principalKind: "api_key",
+            ...service,
           },
         ]
       : [],
     defaultAccountId: apiKey.accountId,
     defaultWorkspaceId: apiKey.workspaceId,
-  } satisfies AccessContext;
+  };
+  if (service) apiKeyServiceContexts.set(context, service);
+  if (
+    apiKey.credentialKind === "organization" &&
+    organizationApiKeyAccess(apiKey.permissions) === "developer_setup"
+  ) {
+    developerSetupApiKeyContexts.add(context);
+  }
   if (apiKey.workspaceId === null && apiKey.credentialKind === "organization") {
     accountScopedApiKeyContexts.set(
       context,
       Object.freeze({
         accountId: apiKey.accountId,
+        workspaceScope: apiKey.workspaceScope ?? { kind: "all" as const },
+        permissionMode: apiKey.permissionMode ?? "legacy",
         permissions: Object.freeze(
           apiKey.permissions.filter(
             (permission) => !accountScopedApiKeyWorkspaceExcludedPermissions.has(permission),
@@ -894,6 +1785,32 @@ async function apiKeyAccessContext(
       }),
     );
   }
+  // Report the exact stamped authority consumed by accessGrantAuthorization,
+  // rather than re-deriving organization-key permissions from a separate rule.
+  // This projection is never an authorization input, and the asUser branch
+  // above deliberately omits it instead of advertising the service's authority.
+  const authority = accountScopedApiKeyWorkspaceAuthority(context);
+  const workspaceGrant =
+    apiKey.credentialKind === "workspace" ? context.workspaceGrants[0] : undefined;
+  const workspacePermissions = authority?.permissions ?? workspaceGrant?.permissions;
+  if (workspacePermissions) {
+    context.credential = {
+      kind: authority ? "organization_api_key" : "workspace_api_key",
+      ...(authority ? { access: organizationApiKeyAccess(apiKey.permissions) } : {}),
+      accountId: apiKey.accountId,
+      workspaceId: apiKey.workspaceId,
+      effectiveWorkspacePermissions: Permission.options.filter(
+        (permission) =>
+          !(developerSetupApiKeyContexts.has(context) && permission === "api_keys:manage") &&
+          !accountScopedApiKeyWorkspaceExcludedPermissions.has(permission) &&
+          hasPermission(workspacePermissions, permission),
+      ),
+      ...(authority ? { policy: apiKey.policy, workspaceScope: authority.workspaceScope } : {}),
+      note: authority
+        ? `These permissions apply to ${authority.workspaceScope.kind === "all" ? "every" : "selected"} shared workspace${authority.workspaceScope.kind === "all" ? "" : "s"} in this organization, not Personal workspaces. workspaceGrants need not enumerate them; accountGrants report organization-level permissions. asUser requests also require user authority.`
+        : "These permissions apply only to the workspace identified by workspaceId; they grant no organization-wide workspace authority.",
+    };
+  }
   return context;
 }
 
@@ -911,7 +1828,11 @@ async function delegatedAccessContext(
   if (!payload) {
     return null;
   }
-  return {
+  const restricted = payload.credentialRestriction === "developer_setup";
+  const workspacePermissions = restricted
+    ? payload.permissions.filter(isDeveloperSetupDelegatedPermissionAllowed)
+    : payload.permissions;
+  const context: AccessContext = {
     mode,
     subjectId: payload.subjectId,
     ...(payload.subjectLabel ? { subjectLabel: payload.subjectLabel } : {}),
@@ -920,7 +1841,7 @@ async function delegatedAccessContext(
         accountId: payload.accountId,
         subjectId: payload.subjectId,
         ...(payload.subjectLabel ? { subjectLabel: payload.subjectLabel } : {}),
-        permissions: payload.permissions,
+        permissions: restricted ? [] : payload.permissions,
       },
     ],
     workspaceGrants: [
@@ -929,7 +1850,7 @@ async function delegatedAccessContext(
         accountId: payload.accountId,
         subjectId: payload.subjectId,
         ...(payload.subjectLabel ? { subjectLabel: payload.subjectLabel } : {}),
-        permissions: payload.permissions,
+        permissions: workspacePermissions,
         principalKind: payload.principalKind,
         // sessionId is worker-asserted (HMAC-signed token claim), not agent
         // controlled; it scopes session-bound MCP tools such as goal management.
@@ -962,6 +1883,8 @@ async function delegatedAccessContext(
     defaultAccountId: payload.accountId,
     defaultWorkspaceId: payload.workspaceId,
   };
+  if (restricted) developerSetupApiKeyContexts.add(context);
+  return context;
 }
 
 function configuredSubject(c: Context): string {