@pylonsync/functions 0.22.32 → 0.22.33

package/dist/runtime.d.ts

@@ -14,7 +14,7 @@
  *   each ctx.db / ctx.scheduler / ctx.runMutation call), so the map never
  *   needs to queue multiple RPCs per call_id.
  */
-import type { DbReader, DbWriter, Llm, Rooms, Workflows, Audit } from "./types";
+import type { DbReader, DbWriter, Llm, Rooms, Workflows, Audit, ApiKeys } from "./types";
 export declare function buildDbReader(callId: string, ssrRead?: boolean): DbReader;
 export declare function buildSsrFnCaller(callId: string): (name: string, args?: Record<string, unknown>) => Promise<unknown>;
 export declare function buildDbWriter(callId: string): DbWriter;
@@ -48,4 +48,6 @@ export declare function buildRooms(callId: string): Rooms;
  */
 /** Build `ctx.audit` — round-trips `audit_op` frames to the host. */
 export declare function buildAudit(callId: string): Audit;
+/** Build `ctx.apiKeys` — round-trips `api_key_op` frames to the host. */
+export declare function buildApiKeys(callId: string): ApiKeys;
 export declare function buildWorkflows(callId: string): Workflows;

package/dist/types.d.ts

@@ -628,6 +628,46 @@ export interface AuditLog {
         id: string;
     }>;
 }
+/**
+ * `ctx.apiKeys`: API keys for the app's own users, minted from server
+ * code. For a service user the app runs (for example one per AI agent),
+ * where the HTTP route `POST /api/auth/api-keys` does not fit because it
+ * mints a key for the signed-in caller only.
+ *
+ * Actions only. The action must be `internal: true` or have called
+ * `ctx.auth.elevate({ admin: true, reason })` after checking its own
+ * caller; anything else is refused with `API_KEYS_FORBIDDEN`. Not in
+ * mutations: a key is not part of the mutation's transaction.
+ * Every call is in the server log with the function name and user id.
+ */
+export interface ApiKeys {
+    /**
+     * Mint a key for `userId`. The plaintext `key` is returned once and is
+     * never readable again; store it where the key's holder can use it.
+     * `expiresAt` is unix seconds. `name` is a label (at most 100
+     * characters).
+     */
+    create(options: {
+        userId: string;
+        name?: string;
+        expiresAt?: number;
+    }): Promise<{
+        key: string;
+        id: string;
+        prefix: string;
+        expiresAt: number | null;
+    }>;
+    /**
+     * Revoke key `keyId` of `userId`. `revoked` is false when no key of
+     * that user has that id.
+     */
+    revoke(options: {
+        userId: string;
+        keyId: string;
+    }): Promise<{
+        revoked: boolean;
+    }>;
+}
 /**
  * `ctx.audit` on actions: {@link AuditLog.log} plus reads. Mutations get
  * only `log`: in a Postgres mutation the transaction holds a connection,
@@ -1371,6 +1411,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
     workflows: Workflows;
     /** Application audit log — see {@link Audit}. */
     audit: Audit;
+    /** API keys for the app's own users, from server code — see {@link ApiKeys}. */
+    apiKeys: ApiKeys;
     /** Run an `agent()` as a named user from server code — see {@link Agents}. */
     agents: Agents;
     /** Attach / register custom domains for your app's OWN end-customers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.22.32",
+  "version": "0.22.33",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/runtime.ts

@@ -39,6 +39,7 @@ import type {
   WorkflowRunSummary,
   Audit,
   AuditEntry,
+  ApiKeys,
   Connections,
   Domains,
   TenantDomainResult,
@@ -1102,6 +1103,37 @@ export function buildAudit(callId: string): Audit {
   };
 }
 
+/** Build `ctx.apiKeys` — round-trips `api_key_op` frames to the host. */
+export function buildApiKeys(callId: string): ApiKeys {
+  return {
+    async create(options) {
+      // A value Rust cannot read as u64 would be dropped by the host and
+      // leave the call waiting; NaN would turn into "never expires".
+      const exp = options.expiresAt;
+      if (exp !== undefined && !(Number.isSafeInteger(exp) && exp >= 0)) {
+        const err = new Error("ctx.apiKeys.create expiresAt must be a whole number of unix seconds, 0 or more");
+        (err as { code?: string }).code = "INVALID_ARGS";
+        throw err;
+      }
+      return (await rpc(callId, {
+        type: "api_key_op",
+        op: "create",
+        user_id: options.userId,
+        name: options.name ?? null,
+        expires_at: options.expiresAt ?? null,
+      })) as { key: string; id: string; prefix: string; expiresAt: number | null };
+    },
+    async revoke(options) {
+      return (await rpc(callId, {
+        type: "api_key_op",
+        op: "revoke",
+        user_id: options.userId,
+        key_id: options.keyId,
+      })) as { revoked: boolean };
+    },
+  };
+}
+
 export function buildWorkflows(callId: string): Workflows {
   return {
     async start(name: string, input?: unknown, opts?: { key?: string }) {
@@ -1356,6 +1388,7 @@ function buildActionCtx(
     connections,
     workflows: buildWorkflows(callId),
     audit: buildAudit(callId),
+    apiKeys: buildApiKeys(callId),
     agents: {
       async run(name, options) {
         if (!options || typeof options.as?.userId !== "string") {

package/src/types.ts

@@ -705,6 +705,37 @@ export interface AuditLog {
   }): Promise<{ id: string }>;
 }
 
+/**
+ * `ctx.apiKeys`: API keys for the app's own users, minted from server
+ * code. For a service user the app runs (for example one per AI agent),
+ * where the HTTP route `POST /api/auth/api-keys` does not fit because it
+ * mints a key for the signed-in caller only.
+ *
+ * Actions only. The action must be `internal: true` or have called
+ * `ctx.auth.elevate({ admin: true, reason })` after checking its own
+ * caller; anything else is refused with `API_KEYS_FORBIDDEN`. Not in
+ * mutations: a key is not part of the mutation's transaction.
+ * Every call is in the server log with the function name and user id.
+ */
+export interface ApiKeys {
+  /**
+   * Mint a key for `userId`. The plaintext `key` is returned once and is
+   * never readable again; store it where the key's holder can use it.
+   * `expiresAt` is unix seconds. `name` is a label (at most 100
+   * characters).
+   */
+  create(options: {
+    userId: string;
+    name?: string;
+    expiresAt?: number;
+  }): Promise<{ key: string; id: string; prefix: string; expiresAt: number | null }>;
+  /**
+   * Revoke key `keyId` of `userId`. `revoked` is false when no key of
+   * that user has that id.
+   */
+  revoke(options: { userId: string; keyId: string }): Promise<{ revoked: boolean }>;
+}
+
 /**
  * `ctx.audit` on actions: {@link AuditLog.log} plus reads. Mutations get
  * only `log`: in a Postgres mutation the transaction holds a connection,
@@ -1500,6 +1531,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   workflows: Workflows;
   /** Application audit log — see {@link Audit}. */
   audit: Audit;
+  /** API keys for the app's own users, from server code — see {@link ApiKeys}. */
+  apiKeys: ApiKeys;
   /** Run an `agent()` as a named user from server code — see {@link Agents}. */
   agents: Agents;
   /** Attach / register custom domains for your app's OWN end-customers