@opengeni/core 0.2.0

package/src/access/index.ts

@@ -0,0 +1,186 @@
+import type { Settings } from "@opengeni/config";
+import { verifyDelegatedAccessToken, type AccessContext, type AccessGrant, type Permission } from "@opengeni/contracts";
+import {
+  bootstrapWorkspace,
+  ensureManagedAccessForUser,
+  findActiveApiKeyByHash,
+  getWorkspaceGrant,
+  requireWorkspace,
+  type Database,
+} from "@opengeni/db";
+import type { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+import type { ManagedAuth } from "../managed-auth-type";
+
+const bearerPrefix = "Bearer ";
+
+export type AccessDeps = {
+  db: Database;
+  settings: Settings;
+  managedAuth?: ManagedAuth | null;
+};
+
+export async function requireAccessContext(c: Context, deps: AccessDeps): Promise<AccessContext> {
+  const context = await resolveAccessContext(c, deps);
+  if (!context) {
+    throw new HTTPException(401, { message: "authentication required" });
+  }
+  return context;
+}
+
+export async function requireAccessGrant(c: Context, deps: AccessDeps, workspaceId: string, permission?: Permission): Promise<AccessGrant> {
+  const context = await requireAccessContext(c, deps);
+  const grant = context.workspaceGrants.find((candidate) => candidate.workspaceId === workspaceId)
+    ?? await getWorkspaceGrant(deps.db, context.subjectId, workspaceId);
+  if (!grant) {
+    const workspace = await requireWorkspace(deps.db, workspaceId).catch(() => null);
+    if (!workspace) {
+      throw new HTTPException(404, { message: "workspace not found" });
+    }
+    throw new HTTPException(403, { message: "workspace access denied" });
+  }
+  if (permission) {
+    requirePermission(grant, permission);
+  }
+  return grant;
+}
+
+export function requirePermission(grant: AccessGrant, permission: Permission): void {
+  if (!hasPermission(grant.permissions, permission)) {
+    throw new HTTPException(403, { message: `missing permission: ${permission}` });
+  }
+}
+
+export function hasPermission(permissions: Permission[], permission: Permission): boolean {
+  return permissions.includes(permission) || permissions.includes("workspace:admin");
+}
+
+async function resolveAccessContext(c: Context, deps: AccessDeps): Promise<AccessContext | null> {
+  if (deps.settings.productAccessMode === "local") {
+    return await bootstrapWorkspace(deps.db, {
+      accountExternalSource: "opengeni:local",
+      accountExternalId: "default",
+      accountName: "Local",
+      workspaceExternalSource: "opengeni:local",
+      workspaceExternalId: "default",
+      workspaceName: "Local",
+      subjectId: "dev",
+      subjectLabel: "Local dev",
+    });
+  }
+
+	  if (deps.settings.productAccessMode === "configured") {
+	    const delegated = await delegatedAccessContext(c, deps, "configured");
+	    if (delegated) {
+	      return delegated;
+	    }
+	    if (deps.settings.delegationSecret) {
+	      return null;
+	    }
+	    return await bootstrapWorkspace(deps.db, {
+	      accountExternalSource: "opengeni:configured",
+      accountExternalId: "default",
+      accountName: "Configured",
+      workspaceExternalSource: "opengeni:configured",
+      workspaceExternalId: "default",
+      workspaceName: "Configured",
+      subjectId: configuredSubject(c),
+      subjectLabel: "Configured key",
+    });
+  }
+
+  const bearer = bearerToken(c);
+  if (bearer) {
+    const delegated = await delegatedAccessContext(c, deps, "managed", bearer);
+    if (delegated) {
+      return delegated;
+    }
+    const apiKey = await findActiveApiKeyByHash(deps.db, await sha256Hex(bearer));
+    if (apiKey) {
+      const accountPermissions = apiKey.workspaceId
+        ? apiKey.permissions.filter((permission) => permission === "billing:read" || permission === "billing:manage")
+        : apiKey.permissions;
+      return {
+        mode: "managed",
+        subjectId: `api_key:${apiKey.id}`,
+        subjectLabel: apiKey.name,
+        accountGrants: [{
+          accountId: apiKey.accountId,
+          subjectId: `api_key:${apiKey.id}`,
+          subjectLabel: apiKey.name,
+          permissions: accountPermissions,
+        }],
+        workspaceGrants: apiKey.workspaceId ? [{
+          workspaceId: apiKey.workspaceId,
+          accountId: apiKey.accountId,
+          subjectId: `api_key:${apiKey.id}`,
+          subjectLabel: apiKey.name,
+          permissions: apiKey.permissions,
+        }] : [],
+        defaultAccountId: apiKey.accountId,
+        defaultWorkspaceId: apiKey.workspaceId,
+      } satisfies AccessContext;
+    }
+  }
+
+  if (deps.managedAuth) {
+    const session = await deps.managedAuth.api.getSession({ headers: c.req.raw.headers });
+    if (session?.user) {
+      return await ensureManagedAccessForUser(deps.db, {
+        userId: session.user.id,
+        email: session.user.email,
+        name: session.user.name,
+      });
+    }
+  }
+
+  return null;
+}
+
+async function delegatedAccessContext(c: Context, deps: AccessDeps, mode: "configured" | "managed", token = bearerToken(c)): Promise<AccessContext | null> {
+  if (!token || !deps.settings.delegationSecret) {
+    return null;
+  }
+  const payload = await verifyDelegatedAccessToken(deps.settings.delegationSecret, token);
+  if (!payload) {
+    return null;
+  }
+  return {
+    mode,
+    subjectId: payload.subjectId,
+    ...(payload.subjectLabel ? { subjectLabel: payload.subjectLabel } : {}),
+    accountGrants: [{
+      accountId: payload.accountId,
+      subjectId: payload.subjectId,
+      ...(payload.subjectLabel ? { subjectLabel: payload.subjectLabel } : {}),
+      permissions: payload.permissions,
+    }],
+    workspaceGrants: [{
+      workspaceId: payload.workspaceId,
+      accountId: payload.accountId,
+      subjectId: payload.subjectId,
+      ...(payload.subjectLabel ? { subjectLabel: payload.subjectLabel } : {}),
+      permissions: payload.permissions,
+      // sessionId is worker-asserted (HMAC-signed token claim), not agent
+      // controlled; it scopes session-bound MCP tools such as goal management.
+      metadata: { delegated: true, ...(payload.sessionId ? { sessionId: payload.sessionId } : {}) },
+    }],
+    defaultAccountId: payload.accountId,
+    defaultWorkspaceId: payload.workspaceId,
+  };
+}
+
+function configuredSubject(c: Context): string {
+  const header = c.req.header("x-opengeni-subject");
+  return header && header.trim().length > 0 ? `configured:${header.trim()}` : "configured:key";
+}
+
+function bearerToken(c: Context): string | null {
+  const authorization = c.req.header("authorization");
+  return authorization?.startsWith(bearerPrefix) ? authorization.slice(bearerPrefix.length) : null;
+}
+
+async function sha256Hex(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+  return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/src/billing/limits.ts

@@ -0,0 +1,207 @@
+import { configuredStaticUsageLimits } from "@opengeni/config";
+import type { LimitAction, LimitDecision } from "@opengeni/contracts";
+import {
+  countActiveApiKeysForWorkspace,
+  countScheduledTasksForWorkspace,
+  countWorkspacesForAccount,
+  getBillingBalance,
+  isCodexBilledTurn,
+  recordUsageEvent,
+  sumUsageQuantity,
+} from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+import type { ApiRouteDeps } from "../dependencies";
+
+export type LimitCheckInput = {
+  accountId: string;
+  workspaceId?: string;
+  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.
+  model?: string | null;
+};
+
+export async function requireLimit(deps: ApiRouteDeps, 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 });
+}
+
+export async function checkLimit(deps: ApiRouteDeps, input: LimitCheckInput): Promise<LimitDecision> {
+  // Resolve the canonical codex-billed predicate ONCE. Returns false for any
+  // action that carries no model (infra caps) or any codex/<slug> model without
+  // an active credential — so the bypass never triggers on the prefix alone.
+  const codexBilled = input.workspaceId
+    ? await isCodexBilledTurn({ db: deps.db, settings: deps.settings, workspaceId: input.workspaceId, model: input.model })
+    : false;
+  const creditDecision = await checkCreditBalance(deps, input, codexBilled);
+  if (!creditDecision.allowed) {
+    return creditDecision;
+  }
+  if (deps.settings.usageLimitsMode !== "static" && deps.settings.usageLimitsMode !== "managed") {
+    return { allowed: true };
+  }
+  return await checkStaticCaps(deps, input, codexBilled);
+}
+
+async function checkCreditBalance(deps: ApiRouteDeps, input: LimitCheckInput, codexBilled: boolean): Promise<LimitDecision> {
+  if (codexBilled) {
+    return { allowed: true }; // paid by the user's ChatGPT/Codex plan — zero OpenGeni credits
+  }
+  if (!usesCreditLimits(deps) || !isCostlyAction(input.action)) {
+    return { allowed: true };
+  }
+  const balance = await getBillingBalance(deps.db, input.accountId);
+  if (balance.balanceMicros > 0) {
+    return { allowed: true };
+  }
+  return { allowed: false, code: "insufficient_credits", message: "insufficient OpenGeni credits" };
+}
+
+async function checkStaticCaps(deps: ApiRouteDeps, input: LimitCheckInput, codexBilled: boolean): Promise<LimitDecision> {
+  const limits = configuredStaticUsageLimits(deps.settings);
+  if (limits.maxMonthlyCostMicrosPerAccount && isCostlyAction(input.action) && !codexBilled) {
+    const used = await sumUsageQuantity(deps.db, {
+      accountId: input.accountId,
+      eventType: "model.cost",
+      since: startOfUtcMonth(),
+    });
+    if (used >= limits.maxMonthlyCostMicrosPerAccount) {
+      return blocked("max_monthly_cost_micros_per_account", `monthly model cost limit reached (${limits.maxMonthlyCostMicrosPerAccount} micros)`);
+    }
+  }
+  switch (input.action) {
+    case "workspace:create": {
+      if (!limits.maxWorkspacesPerAccount) {
+        return { allowed: true };
+      }
+      const count = await countWorkspacesForAccount(deps.db, input.accountId);
+      return count < limits.maxWorkspacesPerAccount
+        ? { allowed: true }
+        : blocked("max_workspaces_per_account", `workspace limit reached (${limits.maxWorkspacesPerAccount})`);
+    }
+    case "api_key:create": {
+      if (!limits.maxApiKeysPerWorkspace || !input.workspaceId) {
+        return { allowed: true };
+      }
+      const count = await countActiveApiKeysForWorkspace(deps.db, input.workspaceId);
+      return count < limits.maxApiKeysPerWorkspace
+        ? { allowed: true }
+        : blocked("max_api_keys_per_workspace", `API key limit reached (${limits.maxApiKeysPerWorkspace})`);
+    }
+    case "schedule:create": {
+      if (!limits.maxSchedulesPerWorkspace || !input.workspaceId) {
+        return { allowed: true };
+      }
+      const count = await countScheduledTasksForWorkspace(deps.db, input.workspaceId);
+      return count < limits.maxSchedulesPerWorkspace
+        ? { allowed: true }
+        : blocked("max_schedules_per_workspace", `scheduled task limit reached (${limits.maxSchedulesPerWorkspace})`);
+    }
+    case "file:upload": {
+      if (!limits.maxFileUploadBytes || !input.quantity) {
+        return { allowed: true };
+      }
+      return input.quantity <= limits.maxFileUploadBytes
+        ? { allowed: true }
+        : blocked("max_file_upload_bytes", `file upload exceeds static limit of ${limits.maxFileUploadBytes} bytes`);
+    }
+    case "agent_run:create": {
+      if (!limits.maxMonthlyAgentRunsPerWorkspace || !input.workspaceId) {
+        return { allowed: true };
+      }
+      const used = await sumUsageQuantity(deps.db, {
+        workspaceId: input.workspaceId,
+        eventType: "agent_run.created",
+        since: startOfUtcMonth(),
+      });
+      const requested = input.quantity ?? 0;
+      return used + requested <= limits.maxMonthlyAgentRunsPerWorkspace
+        ? { allowed: true }
+        : blocked("max_monthly_agent_runs_per_workspace", `monthly agent run limit reached (${limits.maxMonthlyAgentRunsPerWorkspace})`);
+    }
+    case "tokens:consume": {
+      if (codexBilled || !limits.maxMonthlyTokensPerWorkspace || !input.workspaceId) {
+        return { allowed: true };
+      }
+      const used = await sumUsageQuantity(deps.db, {
+        workspaceId: input.workspaceId,
+        eventType: "model.tokens",
+        since: startOfUtcMonth(),
+      });
+      const requested = input.quantity ?? 0;
+      return used + requested <= limits.maxMonthlyTokensPerWorkspace
+        ? { allowed: true }
+        : blocked("max_monthly_tokens_per_workspace", `monthly token limit reached (${limits.maxMonthlyTokensPerWorkspace})`);
+    }
+    case "document:index": {
+      if (!limits.maxDocumentIndexedChunksPerWorkspace || !input.workspaceId) {
+        return { allowed: true };
+      }
+      const used = await sumUsageQuantity(deps.db, {
+        workspaceId: input.workspaceId,
+        eventType: "document.indexed",
+        since: startOfUtcMonth(),
+      });
+      const requested = input.quantity ?? 0;
+      return used + requested <= limits.maxDocumentIndexedChunksPerWorkspace
+        ? { allowed: true }
+        : blocked("max_document_indexed_chunks_per_workspace", `monthly document indexing limit reached (${limits.maxDocumentIndexedChunksPerWorkspace} chunks)`);
+    }
+  }
+}
+
+export async function recordWorkspaceUsage(deps: ApiRouteDeps, input: {
+  accountId: string;
+  workspaceId: string;
+  subjectId?: string | null;
+  eventType:
+    | "agent_run.created"
+    | "file.uploaded"
+    | "document.indexed"
+    | "scheduled_task.fired";
+  quantity: number;
+  unit: string;
+  sourceResourceType: string;
+  sourceResourceId: string;
+  idempotencyKey: string;
+}): Promise<void> {
+  await recordUsageEvent(deps.db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    subjectId: input.subjectId ?? null,
+    eventType: input.eventType,
+    quantity: input.quantity,
+    unit: input.unit,
+    sourceResourceType: input.sourceResourceType,
+    sourceResourceId: input.sourceResourceId,
+    idempotencyKey: input.idempotencyKey,
+  });
+}
+
+function usesCreditLimits(deps: ApiRouteDeps): boolean {
+  return deps.settings.billingMode === "stripe" || deps.settings.usageLimitsMode === "managed";
+}
+
+function isCostlyAction(action: LimitAction): boolean {
+  return action === "agent_run:create"
+    || action === "tokens:consume"
+    || action === "file:upload"
+    || action === "document:index";
+}
+
+function blocked(code: string, message: string): LimitDecision {
+  return { allowed: false, code, message };
+}
+
+function startOfUtcMonth(): Date {
+  const now = new Date();
+  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+}

package/src/dependencies.ts

@@ -0,0 +1,70 @@
+import type { Settings } from "@opengeni/config";
+import type { Document, ScheduledTask } from "@opengeni/contracts";
+import type { Database } from "@opengeni/db";
+import type { DocumentServices } from "@opengeni/documents";
+import type { EventBus } from "@opengeni/events";
+import type { Observability } from "@opengeni/observability";
+import type { createObjectStorage } from "@opengeni/storage";
+import type { ManagedAuth } from "./managed-auth-type";
+import type { ApiSandboxClient, ResumeBoxByIdInput, ResumedSandboxSession } from "./sandbox-types";
+
+export type SessionWorkflowClient = {
+  signalUserMessage: (input: { sessionId: string; eventId: string; workflowId: string }) => Promise<void>;
+  wakeSessionWorkflow: (input: { accountId: string; workspaceId: string; sessionId: string; workflowId: string }) => Promise<void>;
+  signalApprovalDecision: (input: { sessionId: string; eventId: string; workflowId: string }) => Promise<void>;
+  // Interrupt must reach the workflow whether or not an execution is currently
+  // running: a long-lived session that has gone idle (its workflow returned
+  // after markSessionIdle) has NO running execution, so a plain
+  // getHandle().signal() throws WorkflowNotFoundError -> a 500 that leaves an
+  // operator unable to stop a session. signalWithStart start-or-signals, so it
+  // needs the session-workflow args (accountId/workspaceId) to start a fresh
+  // run when none is live; the buffered `interrupt` signal is then honored by
+  // the workflow's idle-interrupt path (pause goal + mark idle).
+  signalInterrupt: (input: { accountId: string; workspaceId: string; sessionId: string; eventId: string; workflowId: string }) => Promise<void>;
+  syncScheduledTask: (input: { task: ScheduledTask }) => Promise<void>;
+  deleteScheduledTaskSchedule: (input: { temporalScheduleId: string }) => Promise<void>;
+  triggerScheduledTask: (input: { task: ScheduledTask; agentRunUsageIdempotencyKey?: string; triggerWorkflowId?: string }) => Promise<void>;
+};
+
+export type DocumentIndexClient = {
+  indexDocument: (input: { accountId: string; workspaceId: string; documentId: string }) => Promise<Document | void>;
+};
+
+export type AppDependencies = {
+  settings: Settings;
+  db: Database;
+  bus: EventBus;
+  workflowClient: SessionWorkflowClient;
+  documentIndexer?: DocumentIndexClient;
+  documentServices?: DocumentServices;
+  observability?: Observability;
+  githubStateSecret?: string;
+  managedAuth?: ManagedAuth | null;
+  // The API process's OWN agent-loop-free sandbox client (constructed from
+  // settings via @opengeni/runtime/sandbox). Undefined when sandboxBackend=none.
+  // This is the foundation of the API-direct control plane: the API resumes
+  // boxes by id in-process, no Temporal/worker for non-turn ops. Optional on
+  // construction (createApp builds it from settings when absent) so existing
+  // tests that pass a minimal deps bag keep working.
+  sandboxClient?: ApiSandboxClient;
+  /**
+   * Resume a box by id from a serialized resume_state envelope (the lease's
+   * `resume_state` + `resume_backend_id` from P1.1) and return a live session
+   * for a single in-process op. resume → use → drop; the lease owns lifecycle,
+   * the returned handle does NOT own the box. Throws SandboxResumeError on a
+   * backend mismatch or a resume failure.
+   */
+  resumeBoxById?: (input: ResumeBoxByIdInput) => Promise<ResumedSandboxSession>;
+};
+
+export type ObjectStorageDependency = ReturnType<typeof createObjectStorage>;
+
+export type ApiRouteDeps = AppDependencies & {
+  objectStorage: ObjectStorageDependency;
+  githubStateSecret: string;
+  documentIndexer: DocumentIndexClient;
+  getDocumentServices: () => DocumentServices;
+  // Resolved by createApp from settings: routes always get a concrete
+  // resumeBoxById (it throws SandboxResumeError when sandboxBackend=none).
+  resumeBoxById: (input: ResumeBoxByIdInput) => Promise<ResumedSandboxSession>;
+};