@opengeni/core 0.28.0 → 1.0.0

package/src/application/user-resource-grants.ts

@@ -0,0 +1,154 @@
+import type {
+  IssueUserResourceGrantRequest,
+  Permission,
+  SessionAuthorizationSurface,
+  UserResourceKind,
+} from "@opengeni/contracts";
+import {
+  issueSelfUserResourceGrant,
+  listSelfUserResourceAuthorities,
+  revokeSelfUserResourceGrant,
+  sessionTenancyProductActivated,
+  SessionTenancyNotActivatedError,
+} from "@opengeni/db";
+import { requirePermission, type AccessGrantAuthorization } from "../access";
+import type { AppDependencies } from "../dependencies";
+import { requireSessionAuthorization } from "../session-authorization";
+import {
+  requireVerifiedOwningUser,
+  SessionTenancyManagedHumanRequiredError,
+} from "./session-tenancy";
+
+type UserResourceGrantDependencies = Pick<AppDependencies, "db" | "sessionAuthorization">;
+
+const LIST_PERMISSIONS = {
+  connection: ["connections:read"],
+  document: ["documents:search"],
+  variable_set: ["variable-sets:list"],
+  rig: ["rigs:use"],
+  connected_machine: ["enrollments:read"],
+} as const satisfies Record<UserResourceKind, readonly Permission[]>;
+
+const ISSUE_PERMISSIONS = {
+  connection: ["connections:read"],
+  document: ["documents:search"],
+  variable_set: ["variable-sets:list", "variable-sets:attach", "variable-sets:use"],
+  rig: ["rigs:use"],
+  connected_machine: ["enrollments:read"],
+} as const satisfies Record<UserResourceKind, readonly Permission[]>;
+
+async function requireOwnerProductGate(
+  deps: Pick<UserResourceGrantDependencies, "db">,
+  authorization: AccessGrantAuthorization,
+  workspaceId: string,
+  permissions: readonly Permission[],
+): Promise<void> {
+  // Target-free gates must run before an optional target-session lookup or host
+  // callback so rejected principals cannot use grant management as an oracle.
+  requireOwnerAuthority(authorization, workspaceId, permissions);
+  if (!(await sessionTenancyProductActivated(deps.db, workspaceId))) {
+    throw new SessionTenancyNotActivatedError();
+  }
+}
+
+function requireOwnerAuthority(
+  authorization: AccessGrantAuthorization,
+  workspaceId: string,
+  permissions: readonly Permission[],
+): void {
+  if (!authorization.canonicalLocalHumanSession) {
+    requireVerifiedOwningUser(authorization, workspaceId);
+  } else if (
+    !authorization.contextIntegrity ||
+    authorization.authenticatedSubjectId !== authorization.grant.subjectId ||
+    authorization.grant.workspaceId !== workspaceId
+  ) {
+    throw new SessionTenancyManagedHumanRequiredError();
+  }
+  for (const permission of permissions) requirePermission(authorization.grant, permission);
+}
+
+export async function listManagedHumanUserResourceAuthorities(
+  deps: Pick<UserResourceGrantDependencies, "db">,
+  authorization: AccessGrantAuthorization,
+  workspaceId: string,
+  input: { resourceKind: UserResourceKind; cursor?: string | undefined; limit: number },
+) {
+  requireOwnerAuthority(authorization, workspaceId, LIST_PERMISSIONS[input.resourceKind]);
+  // Before activation there cannot be usable personal-resource authority in
+  // this organization. Discovery therefore has an exact empty answer; only
+  // issue/revoke and runtime use remain behind the forward-only product gate.
+  // This keeps ordinary workspace-owned Rig/Variable Set selection independent
+  // from an optional personal-resource product that is not enabled.
+  if (!(await sessionTenancyProductActivated(deps.db, workspaceId))) {
+    return { authorities: [], nextCursor: null };
+  }
+  return await listSelfUserResourceAuthorities(deps.db, {
+    accountId: authorization.grant.accountId,
+    workspaceId,
+    subjectId: authorization.grant.subjectId,
+    ...input,
+  });
+}
+
+export async function issueManagedHumanUserResourceGrant(
+  deps: UserResourceGrantDependencies,
+  authorization: AccessGrantAuthorization,
+  workspaceId: string,
+  authorityId: string,
+  request: IssueUserResourceGrantRequest,
+  authorizationSurface: SessionAuthorizationSurface = "core",
+) {
+  const modePermissions: Permission[] =
+    request.mode === "session" ? ["sessions:control"] : ["sessions:create"];
+  if (authorization.canonicalLocalHumanSession) {
+    throw new SessionTenancyManagedHumanRequiredError();
+  }
+  await requireOwnerProductGate(deps, authorization, workspaceId, [
+    ...ISSUE_PERMISSIONS[request.resourceKind],
+    ...modePermissions,
+  ]);
+
+  if (request.mode === "session") {
+    // Contract refinement guarantees both fields. Keep the defensive check so
+    // direct core callers cannot accidentally weaken the target fence.
+    if (!request.sessionId || !request.expectedAuthorityEpoch) {
+      throw new TypeError("session grant requires its exact authority epoch");
+    }
+    await requireSessionAuthorization(deps, authorization.grant, {
+      sessionId: request.sessionId,
+      operation: "session.personal_resource.grant",
+      surface: authorizationSurface,
+    });
+  }
+
+  return await issueSelfUserResourceGrant(deps.db, {
+    accountId: authorization.grant.accountId,
+    workspaceId,
+    subjectId: authorization.grant.subjectId,
+    authorityId,
+    resourceKind: request.resourceKind,
+    mode: request.mode,
+    context: request.context,
+    sessionId: request.sessionId ?? null,
+    expectedAuthorityEpoch: request.expectedAuthorityEpoch ?? null,
+    workspaceSharedAcknowledged: request.workspaceSharedAcknowledged,
+  });
+}
+
+export async function revokeManagedHumanUserResourceGrant(
+  deps: Pick<UserResourceGrantDependencies, "db">,
+  authorization: AccessGrantAuthorization,
+  workspaceId: string,
+  grantId: string,
+) {
+  // Revocation narrows authority. It intentionally does not require the
+  // resource-specific permission that may have been removed since issuance.
+  await requireOwnerProductGate(deps, authorization, workspaceId, []);
+  return await revokeSelfUserResourceGrant(deps.db, {
+    accountId: authorization.grant.accountId,
+    workspaceId,
+    subjectId: authorization.grant.subjectId,
+    grantId,
+  });
+}

package/src/billing/limits.ts

@@ -1,4 +1,8 @@
-import { configuredStaticUsageLimits } from "@opengeni/config";
+import {
+  configuredStaticUsageLimits,
+  resolveModelProviderForTurn,
+  type Settings,
+} from "@opengeni/config";
 import type {
   LimitAction,
   LimitDecision,
@@ -7,7 +11,9 @@ import type {
   TurnInitiatorContext,
 } from "@opengeni/contracts";
 import {
+  checkWorkspaceAllowance,
   countActiveApiKeysForWorkspace,
+  countActiveOrganizationApiKeysForAccount,
   countScheduledTasksForWorkspace,
   countWorkspacesForAccount,
   getBillingBalance,
@@ -20,28 +26,74 @@ import type { ApiRouteDeps } from "../dependencies";
 
 export type LimitDependencies = Pick<ApiRouteDeps, "db" | "settings">;
 
+/** Deterministic/local embeddings never debit credits, even in paid mode. */
+export function paidDocumentEmbedding(settings: Settings): boolean {
+  return (
+    settings.documentEmbeddingBillingMode === "credits" &&
+    settings.documentEmbeddingProvider === "openai"
+  );
+}
+
+/** Round up each provider request so a positive input cannot become a free debit. */
+export function documentEmbeddingCostMicros(settings: Settings, inputBytes: number): number {
+  if (!Number.isSafeInteger(inputBytes) || inputBytes < 0)
+    throw new Error("invalid embedding bytes");
+  const amount =
+    (BigInt(inputBytes) * BigInt(settings.documentEmbeddingRateMicrosPerMillionBytes) + 999_999n) /
+    1_000_000n;
+  if (amount > BigInt(Number.MAX_SAFE_INTEGER))
+    throw new Error("embedding cost exceeds safe integer");
+  return Number(amount);
+}
+
 export type LimitCheckInput = {
   accountId: string;
   workspaceId?: string;
+  /** Frozen causal human, never the API key or service admitting the work. */
+  initiatingHumanSubjectId?: string | null;
   action: LimitAction;
   quantity?: number;
-  // The turn's model id, when the action represents an agent turn. When this is a
-  // Codex-billed turn (codex/<slug> + feature enabled + active workspace
-  // credential) the turn is paid by the user's ChatGPT/Codex plan and consumes
-  // ZERO OpenGeni credits, so the credit-balance + model-cost + token gates are
-  // skipped. Non-model infra actions (workspace/api_key/schedule create) leave
-  // this undefined and are unaffected.
+  // The turn's model id, when the action represents an agent turn. The model's
+  // deployment cost controls credit/cost gates; upstream metering independently
+  // controls the token cap. Connected subscriptions still require live workspace
+  // readiness. Non-model infra actions leave this undefined.
   model?: string | null;
 };
 
+export function modelFundingForAdmission(
+  settings: Settings,
+  model: string | null | undefined,
+  codexBilled: boolean,
+): { fundedWithoutCredits: boolean; countsTowardTokenCap: boolean } {
+  const resolvedModel = model ? resolveModelProviderForTurn(settings, model)?.model : null;
+  const codexSubscriptionModel =
+    resolvedModel?.credentialSource.kind === "connected_subscription" &&
+    resolvedModel.credentialSource.provider === "codex";
+  return {
+    // A Codex namespace/definition never bypasses credits by itself: the live
+    // workspace credential predicate above remains authoritative. SuperGrok's
+    // static overlay is likewise secret-free; its worker/provider admission
+    // owns live account selection before any upstream request can occur.
+    fundedWithoutCredits:
+      codexBilled ||
+      (resolvedModel != null && !codexSubscriptionModel && resolvedModel.cost !== "credits"),
+    countsTowardTokenCap:
+      !codexBilled && resolvedModel != null && resolvedModel.billing.upstreamPayer === "deployment",
+  };
+}
+
 export async function requireLimit(deps: LimitDependencies, input: LimitCheckInput): Promise<void> {
   const decision = await checkLimit(deps, input);
   if (decision.allowed) {
     return;
   }
-  throw new HTTPException(decision.code === "insufficient_credits" ? 402 : 429, {
-    message: decision.message,
-  });
+  throw new HTTPException(
+    decision.code === "insufficient_credits" || decision.code === "allowance_exhausted" ? 402 : 429,
+    {
+      message: decision.message,
+      cause: decision,
+    },
+  );
 }
 
 export async function checkLimit(
@@ -59,23 +111,39 @@ export async function checkLimit(
         model: input.model,
       })
     : false;
-  const creditDecision = await checkCreditBalance(deps, input, codexBilled);
+  const { fundedWithoutCredits, countsTowardTokenCap } = modelFundingForAdmission(
+    deps.settings,
+    input.model,
+    codexBilled,
+  );
+  const creditDecision = await checkCreditBalance(deps, input, fundedWithoutCredits);
   if (!creditDecision.allowed) {
     return creditDecision;
   }
+  if (!fundedWithoutCredits && isCostlyAction(input.action) && input.workspaceId) {
+    const refusal = await checkWorkspaceAllowance(deps.db, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      subjectId: input.initiatingHumanSubjectId ?? null,
+    });
+    if (refusal) return { allowed: false, ...refusal };
+  }
   if (deps.settings.usageLimitsMode !== "static" && deps.settings.usageLimitsMode !== "managed") {
     return { allowed: true };
   }
-  return await checkStaticCaps(deps, input, codexBilled);
+  return await checkStaticCaps(deps, input, {
+    fundedWithoutCredits,
+    countsTowardTokenCap,
+  });
 }
 
 async function checkCreditBalance(
   deps: LimitDependencies,
   input: LimitCheckInput,
-  codexBilled: boolean,
+  externallyBilled: boolean,
 ): Promise<LimitDecision> {
-  if (codexBilled) {
-    return { allowed: true }; // paid by the user's ChatGPT/Codex plan — zero OpenGeni credits
+  if (externallyBilled) {
+    return { allowed: true }; // paid outside OpenGeni — zero OpenGeni credits
   }
   if (!usesCreditLimits(deps) || !isCostlyAction(input.action)) {
     return { allowed: true };
@@ -84,16 +152,20 @@ async function checkCreditBalance(
   if (balance.balanceMicros > 0) {
     return { allowed: true };
   }
-  return { allowed: false, code: "insufficient_credits", message: "insufficient OpenGeni credits" };
+  return { allowed: false, code: "insufficient_credits", message: "insufficient Opengeni credits" };
 }
 
 async function checkStaticCaps(
   deps: LimitDependencies,
   input: LimitCheckInput,
-  codexBilled: boolean,
+  funding: { fundedWithoutCredits: boolean; countsTowardTokenCap: boolean },
 ): Promise<LimitDecision> {
   const limits = configuredStaticUsageLimits(deps.settings);
-  if (limits.maxMonthlyCostMicrosPerAccount && isCostlyAction(input.action) && !codexBilled) {
+  if (
+    limits.maxMonthlyCostMicrosPerAccount &&
+    isCostlyAction(input.action) &&
+    !funding.fundedWithoutCredits
+  ) {
     const used = await sumUsageQuantity(deps.db, {
       accountId: input.accountId,
       eventType: "model.cost",
@@ -120,10 +192,12 @@ async function checkStaticCaps(
           );
     }
     case "api_key:create": {
-      if (!limits.maxApiKeysPerWorkspace || !input.workspaceId) {
+      if (!limits.maxApiKeysPerWorkspace) {
         return { allowed: true };
       }
-      const count = await countActiveApiKeysForWorkspace(deps.db, input.workspaceId);
+      const count = input.workspaceId
+        ? await countActiveApiKeysForWorkspace(deps.db, input.workspaceId)
+        : await countActiveOrganizationApiKeysForAccount(deps.db, input.accountId);
       return count < limits.maxApiKeysPerWorkspace
         ? { allowed: true }
         : blocked(
@@ -172,7 +246,11 @@ async function checkStaticCaps(
           );
     }
     case "tokens:consume": {
-      if (codexBilled || !limits.maxMonthlyTokensPerWorkspace || !input.workspaceId) {
+      if (
+        !funding.countsTowardTokenCap ||
+        !limits.maxMonthlyTokensPerWorkspace ||
+        !input.workspaceId
+      ) {
         return { allowed: true };
       }
       const used = await sumUsageQuantity(deps.db, {
@@ -253,9 +331,10 @@ function usesCreditLimits(deps: LimitDependencies): boolean {
 }
 
 function isCostlyAction(action: LimitAction): boolean {
-  return (
-    action === "agent_run:create" || action === "tokens:consume" || action === "document:index"
-  );
+  // Document admission retains the monthly chunk quota above, but parsing and
+  // source retention do not consume embedding credits. The worker admits paid
+  // embedding separately and settles its actual provider input after use.
+  return action === "agent_run:create" || action === "tokens:consume";
 }
 
 function blocked(code: string, message: string): LimitDecision {

package/src/canonical-human-identities.ts

@@ -3,6 +3,13 @@ import type { Context } from "hono";
 import { HTTPException } from "hono/http-exception";
 import type { ManagedAuth } from "./managed-auth-type";
 import { getManagedSession } from "./managed-session";
+export {
+  getManagedAuthRequestActorAdmissionStamp,
+  getManagedAuthRequestActorLeaseStamp,
+  markManagedAuthRequestActorTransitionApplied,
+} from "./managed-session";
+import type { ManagedAuthSessionAdapter } from "./managed-auth-session-sets";
+import type { ManagedAuthSessionSetMode } from "@opengeni/contracts/managed-auth-session-sets";
 
 export type CanonicalHumanRequestIdentity = {
   authUserId: string;
@@ -11,17 +18,29 @@ export type CanonicalHumanRequestIdentity = {
 
 export async function requireCanonicalHumanRequestIdentity(
   context: Context,
-  input: { db: Database; managedAuth?: ManagedAuth | null; allowRecovery?: boolean },
+  input: {
+    db: Database;
+    managedAuth?: ManagedAuth | null | undefined;
+    managedAuthSessionAdapter?: ManagedAuthSessionAdapter | null | undefined;
+    managedAuthSessionSetMode?: ManagedAuthSessionSetMode | undefined;
+    allowRecovery?: boolean | undefined;
+  },
 ): Promise<CanonicalHumanRequestIdentity> {
   if (!input.managedAuth) {
-    throw new HTTPException(404, { message: "Canonical human identity is unavailable" });
+    throw new HTTPException(404, {
+      message: "Canonical human identity is unavailable",
+    });
   }
   const session = await getManagedSession(context, input.managedAuth, {
     db: input.db,
+    sessionAdapter: input.managedAuthSessionAdapter,
+    sessionSetMode: input.managedAuthSessionSetMode,
     ...(input.allowRecovery === undefined ? {} : { allowIdentityRecovery: input.allowRecovery }),
   });
   if (!session?.user || typeof session.session?.id !== "string") {
-    throw new HTTPException(401, { message: "Managed human authentication required" });
+    throw new HTTPException(401, {
+      message: "Managed human authentication required",
+    });
   }
   return { authUserId: session.user.id, authSessionId: session.session.id };
 }

package/src/codex-model-availability.ts

@@ -0,0 +1,136 @@
+import { CODEX_CLIENT_VERSION, fetchCodexModels } from "@opengeni/codex";
+import { configuredModels, withCodexCatalogProvider, type Settings } from "@opengeni/config";
+import {
+  buildCodexTokenResolver,
+  connectionModelAllowed,
+  getCodexRotationSettings,
+  listCodexAccountStatuses,
+  loadCodexCredentialForRun,
+  type Database,
+} from "@opengeni/db";
+import type { ModelAvailabilityObservation } from "./model-catalog";
+
+const CATALOG_CACHE_MS = 60_000;
+const CATALOG_ERROR_CACHE_MS = 5_000;
+type CatalogCacheEntry = {
+  expiresAt: number;
+  result: Promise<{ ok: boolean; slugs: string[]; checkedAt: string }>;
+};
+const catalogs = new Map<string, CatalogCacheEntry>();
+
+type Dependencies = {
+  listAccounts: typeof listCodexAccountStatuses;
+  getRotation: typeof getCodexRotationSettings;
+  loadCredential: typeof loadCodexCredentialForRun;
+  fetchModels: typeof fetchCodexModels;
+  getToken: (
+    db: Database,
+    settings: Settings,
+    workspaceId: string,
+    credentialId: string,
+  ) => ReturnType<ReturnType<typeof buildCodexTokenResolver>["getToken"]>;
+};
+
+/** Live provider support is separate from deployment membership and model permissions. */
+export async function loadWorkspaceCodexModelAvailability(
+  db: Database,
+  settings: Settings,
+  workspaceId: string,
+  deps: Dependencies = {
+    listAccounts: listCodexAccountStatuses,
+    getRotation: getCodexRotationSettings,
+    loadCredential: loadCodexCredentialForRun,
+    fetchModels: fetchCodexModels,
+    getToken: (targetDb, targetSettings, targetWorkspaceId, credentialId) =>
+      buildCodexTokenResolver(targetDb, targetSettings, targetWorkspaceId, credentialId).getToken(),
+  },
+): Promise<Record<string, ModelAvailabilityObservation>> {
+  if (!settings.codexSubscriptionEnabled) return {};
+  const [accounts, rotation] = await Promise.all([
+    deps.listAccounts(db, workspaceId),
+    deps.getRotation(db, workspaceId),
+  ]);
+  const candidates = accounts.filter(
+    (account) =>
+      account.status === "active" &&
+      account.allocatorEnabled &&
+      (rotation?.rotationEnabled || account.isActive),
+  );
+  const live = await Promise.all(
+    candidates.map(async (account) => {
+      const unavailable = () => ({
+        account,
+        ok: false,
+        slugs: [] as string[],
+        checkedAt: new Date().toISOString(),
+      });
+      try {
+        // Recheck current workspace/source authority before consulting the cache.
+        const credential = await deps.loadCredential(db, settings, workspaceId, account.id);
+        if (!credential || credential.status !== "active") return unavailable();
+        let key = `${workspaceId}:${credential.id}:${credential.version}`;
+        let cached = catalogs.get(key);
+        if (!cached || cached.expiresAt <= Date.now()) {
+          const token = await deps.getToken(db, settings, workspaceId, credential.id);
+          key = `${workspaceId}:${credential.id}:${token.credentialVersion}`;
+          cached = catalogs.get(key);
+          if (cached && cached.expiresAt > Date.now()) {
+            return { account, ...(await cached.result) };
+          }
+          for (const [id, entry] of catalogs) {
+            if (entry.expiresAt <= Date.now()) catalogs.delete(id);
+          }
+          if (catalogs.size >= 1_024) catalogs.delete(catalogs.keys().next().value!);
+          const entry: CatalogCacheEntry = {
+            expiresAt: Date.now() + CATALOG_CACHE_MS,
+            result: deps
+              .fetchModels({
+                accessToken: token.accessToken,
+                chatgptAccountId: token.chatgptAccountId,
+                isFedramp: token.isFedramp,
+                clientVersion: CODEX_CLIENT_VERSION,
+              })
+              .catch(() => ({ ok: false, slugs: [] as string[] }))
+              .then((result) => {
+                entry.expiresAt =
+                  Date.now() + (result.ok ? CATALOG_CACHE_MS : CATALOG_ERROR_CACHE_MS);
+                return { ok: result.ok, slugs: result.slugs, checkedAt: new Date().toISOString() };
+              }),
+          };
+          catalogs.set(key, entry);
+          cached = entry;
+        }
+        return { account, ...(await cached.result) };
+      } catch {
+        return unavailable();
+      }
+    }),
+  );
+  return Object.fromEntries(
+    configuredModels(withCodexCatalogProvider(settings))
+      .filter(
+        (model) =>
+          model.credentialSource.kind === "connected_subscription" &&
+          model.credentialSource.provider === "codex",
+      )
+      .map((model) => {
+        // Support and permission must hold on the SAME serving account.
+        const permitted = live.filter(({ account }) =>
+          connectionModelAllowed(account.allowedModelIds, model.id),
+        );
+        // The allocator may choose any permitted candidate, so all must support it.
+        const supported =
+          permitted.length > 0 &&
+          permitted.every(({ ok, slugs }) => ok && slugs.includes(model.upstreamModelId));
+        const uncertain = permitted.find(({ ok }) => !ok);
+        return [
+          model.definitionVersion,
+          {
+            status: supported ? "available" : "unavailable",
+            reason: supported ? null : uncertain ? "provider_unhealthy" : "not_entitled",
+            checkedAt: (uncertain ?? permitted[0])?.checkedAt ?? new Date().toISOString(),
+          } satisfies ModelAvailabilityObservation,
+        ];
+      }),
+  );
+}