@homespunapps/core 1.6.43 → 1.6.45

package/dist/app-stream.d.ts

@@ -40,6 +40,10 @@ export interface AppStreamHandlers {
     onResync?: () => void;
     /** Fired on the terminal `_dormant` frame (the app went dormant). */
     onDormant?: () => void;
+    /** Fired on the terminal `_suspended` frame (an operator suspended the
+     *  app, issue #1041). Distinct from `onDormant`: there is no self-service
+     *  recovery here, only an operator can unsuspend. */
+    onSuspended?: () => void;
     /** Fired on a relay-side error frame. */
     onRelayError?: (error: {
         code?: string;

package/dist/app-stream.js

@@ -12,6 +12,7 @@
 //   server -> client  {"type":"entry","entry":{...}}            (live push)
 //   server -> client  {"type":"resync"}                          (since below retention floor)
 //   server -> client  {"type":"_dormant"}                        (terminal — app went dormant)
+//   server -> client  {"type":"_suspended"}                      (terminal: operator takedown, #1041)
 //   server -> client  {"type":"error","error":{...}}
 //
 // `openAppStream` sends the initial `sub` itself (from `opts.since`) and
@@ -94,6 +95,9 @@ export function openAppStream(opts, handlers) {
             case "_dormant":
                 handlers.onDormant?.();
                 return;
+            case "_suspended":
+                handlers.onSuspended?.();
+                return;
             case "error":
                 handlers.onRelayError?.(obj["error"]);
                 return;

package/dist/client.d.ts

@@ -313,7 +313,7 @@ export declare class HomespunClient {
      * human-given slug to an id (see the class-level note above).
      */
     listApps(opts?: {
-        status?: "active" | "dormant" | "archived" | "all";
+        status?: "active" | "dormant" | "archived" | "suspended" | "all";
         limit?: number;
         cursor?: string;
         slug?: string;
@@ -553,6 +553,99 @@ export declare class HomespunClient {
     }>;
     /** DELETE /v1/apps/:id/grants/:grantId: revoke one grant link (idempotent). */
     revokeAppGrant(appId: string, grantId: string): Promise<void>;
+    /**
+     * POST /v1/apps/:id/credentials: mint a service credential scoped to the
+     * named collections and operations. `mode` defaults to "explicit" (an
+     * unnamed collection is denied); "following" tracks the app as it grows,
+     * with each `grants` entry narrowing one collection. `ttlSeconds: null` is
+     * the explicit opt-in to NO EXPIRY; omit for the server's bounded default.
+     * Returns the raw `token` once: only its hash is stored.
+     */
+    mintAppCredential(appId: string, opts?: {
+        mode?: "explicit" | "following";
+        grants?: ServiceCredentialGrant[];
+        members?: boolean;
+        label?: string;
+        ttlSeconds?: number | null;
+    }): Promise<MintAppCredentialResult>;
+    /**
+     * GET /v1/apps/:id/credentials: list the app's service credentials with
+     * their allowlist and status. Never any token material beyond the display
+     * prefix, which is not an authenticator.
+     */
+    listAppCredentials(appId: string): Promise<{
+        credentials: AppCredentialSummary[];
+    }>;
+    /**
+     * POST /v1/apps/:id/credentials/:credentialId/pause: reversible stop, in
+     * force on the credential's very next request. Idempotent.
+     */
+    pauseAppCredential(appId: string, credentialId: string): Promise<void>;
+    /**
+     * POST /v1/apps/:id/credentials/:credentialId/resume: undo a pause. Never
+     * undoes a revoke, which is permanent. Idempotent.
+     */
+    resumeAppCredential(appId: string, credentialId: string): Promise<void>;
+    /**
+     * POST /v1/apps/:id/credentials/:credentialId/rotate: issue a fresh token
+     * and keep the superseded one resolving for `overlapSeconds` (default the
+     * server's own default) so a running backend can pick up the new one
+     * without a gap. Returns the new raw token once, exactly as mint does.
+     */
+    rotateAppCredential(appId: string, credentialId: string, opts?: {
+        overlapSeconds?: number;
+    }): Promise<RotateAppCredentialResult>;
+    /**
+     * DELETE /v1/apps/:id/credentials/:credentialId: revoke one credential
+     * permanently. Also kills any superseded token still inside a rotation
+     * overlap window. Idempotent.
+     */
+    revokeAppCredential(appId: string, credentialId: string): Promise<void>;
+    /**
+     * POST /v1/apps/:id/connections: create a connection. `kind` defaults to
+     * "static" (name + allowedHost + headerName + headerValue). For
+     * `kind: "oauth2"` the caller supplies the WHOLE provider config
+     * (authorizeUrl, tokenEndpoint, clientId, clientSecret, allowedHost, and
+     * the optional scopes/authScheme/instanceField/authParams/tokenParams);
+     * the row starts in `pending_auth` until the signed-in OWNER completes
+     * consent in a browser at `connectionAuthorizeUrl` (an agent key cannot
+     * complete OAuth consent). Every stored secret is encrypted at rest and
+     * never returned by any call.
+     */
+    createConnection(appId: string, body: {
+        name: string;
+        kind?: "static" | "oauth2";
+        provider?: string;
+        label?: string;
+        allowedHost: string;
+        headerName?: string;
+        headerValue?: string;
+        authorizeUrl?: string;
+        tokenEndpoint?: string;
+        clientId?: string;
+        clientSecret?: string;
+        scopes?: string;
+        authScheme?: string;
+        instanceField?: string;
+        authParams?: Record<string, unknown>;
+        tokenParams?: Record<string, unknown>;
+    }): Promise<{
+        connection: ConnectionSummary;
+    }>;
+    /** GET /v1/apps/:id/connections: list metadata only, never the secret. */
+    listConnections(appId: string): Promise<{
+        connections: ConnectionSummary[];
+    }>;
+    /** DELETE /v1/apps/:id/connections/:name: idempotent. */
+    deleteConnection(appId: string, name: string): Promise<void>;
+    /**
+     * The browser URL that completes an oauth2 connection's consent. Build
+     * only, never fetch this yourself: it 302s the caller to the third-party
+     * provider, and the relay refuses an agent-key caller here (consent is
+     * inherently a human-in-a-browser step). Hand the URL to the signed-in
+     * owner to open.
+     */
+    connectionAuthorizeUrl(appId: string, name: string): string;
     /**
      * GET /v1/apps/:id/collections/:name — list rows (current-state page).
      *
@@ -1116,6 +1209,71 @@ export interface AppGrantSummary {
     revoked_at: string | null;
     created_at: string;
 }
+/** One collection entry in a service credential's allowlist. */
+export interface ServiceCredentialGrant {
+    collection: string;
+    ops: ("read" | "create" | "update" | "delete")[];
+    /** "own" narrows every row-addressed op to rows this credential wrote last. */
+    scope?: "own";
+}
+/** `POST /v1/apps/:id/credentials` response. `token` is shown ONCE. */
+export interface MintAppCredentialResult {
+    id: string;
+    token: string;
+    token_prefix: string;
+    mode: string;
+    grants: ServiceCredentialGrant[];
+    members: boolean;
+    label: string | null;
+    expires_at: string | null;
+    /** Present + true iff minting cleared the app's egress waiver (#1328). */
+    unrestricted_revoked?: true;
+    unrestricted_notice?: string;
+}
+/** One service credential row from `listAppCredentials` (never any token). */
+export interface AppCredentialSummary {
+    id: string;
+    label: string | null;
+    token_prefix: string;
+    mode: string;
+    grants: ServiceCredentialGrant[];
+    members: boolean;
+    paused: boolean;
+    active: boolean;
+    expires_at: string | null;
+    paused_at: string | null;
+    revoked_at: string | null;
+    rotated_at: string | null;
+    previous_token_prefix: string | null;
+    previous_expires_at: string | null;
+    created_at: string;
+    last_used_at: string | null;
+}
+/** `POST /v1/apps/:id/credentials/:credentialId/rotate` response. */
+export interface RotateAppCredentialResult {
+    id: string;
+    token: string;
+    token_prefix: string;
+    /** The instant the SUPERSEDED token stops resolving. Both work until then. */
+    previous_expires_at: string;
+}
+/** One connection row (never any secret, metadata plus a fingerprint). */
+export interface ConnectionSummary {
+    id: string;
+    name: string;
+    kind: string;
+    provider: string | null;
+    label: string | null;
+    allowedHost: string | null;
+    headerName: string | null;
+    status: string;
+    authScheme: string | null;
+    instanceBaseUrl: string | null;
+    scopes: string | null;
+    expiresAt: string | null;
+    secretFingerprint: string | null;
+    createdAt: string;
+}
 /** One row in an app collection — the shape every row CRUD op returns. */
 export interface AppRow {
     key: string;

package/dist/client.js

@@ -968,6 +968,132 @@ export class HomespunClient {
             this.fail(r);
     }
     // -------------------------------------------------------------------------
+    // Scoped service credentials (#1354, #1355, #1363). The bearer token an app
+    // owner points a backend they host themselves at, carrying an explicitly
+    // enumerated SUBSET of the owner's authority and bound to one app. Shaped on
+    // the grant-link methods above: mint's raw token is returned exactly ONCE
+    // and is never retrievable afterward, list never returns any token
+    // material, and every verb is owner-or-owning-agent only at the relay (a
+    // credential itself can reach none of these).
+    // -------------------------------------------------------------------------
+    /**
+     * POST /v1/apps/:id/credentials: mint a service credential scoped to the
+     * named collections and operations. `mode` defaults to "explicit" (an
+     * unnamed collection is denied); "following" tracks the app as it grows,
+     * with each `grants` entry narrowing one collection. `ttlSeconds: null` is
+     * the explicit opt-in to NO EXPIRY; omit for the server's bounded default.
+     * Returns the raw `token` once: only its hash is stored.
+     */
+    async mintAppCredential(appId, opts = {}) {
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/credentials`, {
+            mode: opts.mode,
+            grants: opts.grants,
+            members: opts.members,
+            label: opts.label,
+            ttl_seconds: opts.ttlSeconds,
+        });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * GET /v1/apps/:id/credentials: list the app's service credentials with
+     * their allowlist and status. Never any token material beyond the display
+     * prefix, which is not an authenticator.
+     */
+    async listAppCredentials(appId) {
+        const r = await this.call("GET", `/v1/apps/${encodeURIComponent(appId)}/credentials`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * POST /v1/apps/:id/credentials/:credentialId/pause: reversible stop, in
+     * force on the credential's very next request. Idempotent.
+     */
+    async pauseAppCredential(appId, credentialId) {
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/credentials/${encodeURIComponent(credentialId)}/pause`);
+        if (!r.ok)
+            this.fail(r);
+    }
+    /**
+     * POST /v1/apps/:id/credentials/:credentialId/resume: undo a pause. Never
+     * undoes a revoke, which is permanent. Idempotent.
+     */
+    async resumeAppCredential(appId, credentialId) {
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/credentials/${encodeURIComponent(credentialId)}/resume`);
+        if (!r.ok)
+            this.fail(r);
+    }
+    /**
+     * POST /v1/apps/:id/credentials/:credentialId/rotate: issue a fresh token
+     * and keep the superseded one resolving for `overlapSeconds` (default the
+     * server's own default) so a running backend can pick up the new one
+     * without a gap. Returns the new raw token once, exactly as mint does.
+     */
+    async rotateAppCredential(appId, credentialId, opts = {}) {
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/credentials/${encodeURIComponent(credentialId)}/rotate`, { overlap_seconds: opts.overlapSeconds });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * DELETE /v1/apps/:id/credentials/:credentialId: revoke one credential
+     * permanently. Also kills any superseded token still inside a rotation
+     * overlap window. Idempotent.
+     */
+    async revokeAppCredential(appId, credentialId) {
+        const r = await this.call("DELETE", `/v1/apps/${encodeURIComponent(appId)}/credentials/${encodeURIComponent(credentialId)}`);
+        if (!r.ok)
+            this.fail(r);
+    }
+    // -------------------------------------------------------------------------
+    // Connections (#1363): the stored credential a webhook rule authenticates
+    // its target with (a static header token, or a full OAuth2 client), bound
+    // to a host so it can never be exfiltrated to another one. There is no
+    // update verb: change a connection by deleting and recreating it.
+    // -------------------------------------------------------------------------
+    /**
+     * POST /v1/apps/:id/connections: create a connection. `kind` defaults to
+     * "static" (name + allowedHost + headerName + headerValue). For
+     * `kind: "oauth2"` the caller supplies the WHOLE provider config
+     * (authorizeUrl, tokenEndpoint, clientId, clientSecret, allowedHost, and
+     * the optional scopes/authScheme/instanceField/authParams/tokenParams);
+     * the row starts in `pending_auth` until the signed-in OWNER completes
+     * consent in a browser at `connectionAuthorizeUrl` (an agent key cannot
+     * complete OAuth consent). Every stored secret is encrypted at rest and
+     * never returned by any call.
+     */
+    async createConnection(appId, body) {
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/connections`, body);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** GET /v1/apps/:id/connections: list metadata only, never the secret. */
+    async listConnections(appId) {
+        const r = await this.call("GET", `/v1/apps/${encodeURIComponent(appId)}/connections`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** DELETE /v1/apps/:id/connections/:name: idempotent. */
+    async deleteConnection(appId, name) {
+        const r = await this.call("DELETE", `/v1/apps/${encodeURIComponent(appId)}/connections/${encodeURIComponent(name)}`);
+        if (!r.ok)
+            this.fail(r);
+    }
+    /**
+     * The browser URL that completes an oauth2 connection's consent. Build
+     * only, never fetch this yourself: it 302s the caller to the third-party
+     * provider, and the relay refuses an agent-key caller here (consent is
+     * inherently a human-in-a-browser step). Hand the URL to the signed-in
+     * owner to open.
+     */
+    connectionAuthorizeUrl(appId, name) {
+        return `${this.baseUrl}/v1/apps/${encodeURIComponent(appId)}/connections/${encodeURIComponent(name)}/authorize`;
+    }
+    // -------------------------------------------------------------------------
     // v2 collection row CRUD + feed catch-up (spec-cli §2.2/§2.3). Same wire
     // shapes as the v1 homespun-records methods above, mounted under
     // /v1/apps/:id/collections/:name instead of /v1/apps/:id/records/:name.

package/dist/feedback-prompt.d.ts

@@ -0,0 +1 @@
+export declare const RELAY_FAILURE_REPORT_HINT = "this failure is homespun's, not a bad argument. If it is not already in your feedback list, file it once as type `bug`, with the error code above, what you expected, and the arguments you passed.";

package/dist/feedback-prompt.js

@@ -0,0 +1,14 @@
+// The one sentence that turns a relay-side failure into a filed report.
+//
+// Both agent-facing surfaces attach this to errors that are homespun's fault:
+// the MCP tool result (packages/mcp/src/tools.ts) and the CLI error envelope
+// (packages/cli/src/output.ts). It lives here so the two cannot drift into
+// saying different things about the same channel.
+//
+// Attached ONLY to 5xx, never to a 4xx. A 4xx is normally the caller's own bad
+// argument, and prompting a report on those would bury the real signal under
+// rows the operator has to triage and close. The deliberate exception is a
+// misleading error message, which the guide's "do not file" list calls out as a
+// documentation bug worth a `note`, and that one needs the agent's judgement, so
+// no automatic hint can catch it.
+export const RELAY_FAILURE_REPORT_HINT = "this failure is homespun's, not a bad argument. If it is not already in your feedback list, file it once as type `bug`, with the error code above, what you expected, and the arguments you passed.";

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { HomespunClient, HomespunApiError } from "./client.js";
-export type { ClientOptions, RelayResponse, AttachmentRef, UploadBlobOptions, PresignBlobOptions, AttachmentTokenMintResponse, ListBlobsOptions, AttachmentTokenAuditEntry, AttachmentTokenListResponse, QueryResponse, AppAsset, DeployAppRequest, DeployAppResponse, RedeployAppRequest, RedeployAppResponse, DeployCheckRequest, DeployCheckResult, KeyMintResult, AppSummary, AppDetail, AppsPage, AppDomain, AppDomainDnsRecord, AppMember, AddAppMemberResult, AppRow, AppRowsPage, ListScalar, ListWhereCondition, ListSortSpec, BatchRowInput, BatchRowResult, BatchResult, BatchWriteOptions, AppFeedEntry, AppFeedPage, CommunitySetupStep, RetentionAxes, CollectionRetentionView, } from "./client.js";
+export type { ClientOptions, RelayResponse, AttachmentRef, UploadBlobOptions, PresignBlobOptions, AttachmentTokenMintResponse, ListBlobsOptions, AttachmentTokenAuditEntry, AttachmentTokenListResponse, QueryResponse, AppAsset, DeployAppRequest, DeployAppResponse, RedeployAppRequest, RedeployAppResponse, DeployCheckRequest, DeployCheckResult, KeyMintResult, AppSummary, AppDetail, AppsPage, AppDomain, AppDomainDnsRecord, AppMember, AddAppMemberResult, AppRow, AppRowsPage, ListScalar, ListWhereCondition, ListSortSpec, BatchRowInput, BatchRowResult, BatchResult, BatchWriteOptions, AppFeedEntry, AppFeedPage, CommunitySetupStep, RetentionAxes, CollectionRetentionView, ServiceCredentialGrant, MintAppCredentialResult, AppCredentialSummary, RotateAppCredentialResult, ConnectionSummary, } from "./client.js";
 export { openStream } from "./stream.js";
 export type { OpenStreamOptions, StreamHandlers, StreamHandle, } from "./stream.js";
 export { openAppStream, appWsUrlFromAppUrl } from "./app-stream.js";
@@ -7,6 +7,7 @@ export type { OpenAppStreamOptions, AppStreamHandlers, AppStreamHandle, } from "
 export { registerAgent } from "./register.js";
 export type { RegisterAgentOptions, RegisterAgentResult } from "./register.js";
 export { feedbackTypeSchema, submitFeedbackSchema } from "./schemas.js";
+export { RELAY_FAILURE_REPORT_HINT } from "./feedback-prompt.js";
 export { validateIconEmoji, isValidIconEmoji, isRasterImageMime, RASTER_ICON_MIME_ALLOWLIST, MAX_ICON_EMOJI_BYTES, } from "./icons.js";
 export type { RasterIconMime } from "./icons.js";
 export { MAX_EVENT_TYPE_LENGTH, MAX_IDEMPOTENCY_KEY_LENGTH, MAX_RESPONSE_SNIPPET_LENGTH, MAX_FRAME_SNIPPET_LENGTH, } from "./limits.js";

package/dist/index.js

@@ -5,5 +5,6 @@ export { openStream } from "./stream.js";
 export { openAppStream, appWsUrlFromAppUrl } from "./app-stream.js";
 export { registerAgent } from "./register.js";
 export { feedbackTypeSchema, submitFeedbackSchema } from "./schemas.js";
+export { RELAY_FAILURE_REPORT_HINT } from "./feedback-prompt.js";
 export { validateIconEmoji, isValidIconEmoji, isRasterImageMime, RASTER_ICON_MIME_ALLOWLIST, MAX_ICON_EMOJI_BYTES, } from "./icons.js";
 export { MAX_EVENT_TYPE_LENGTH, MAX_IDEMPOTENCY_KEY_LENGTH, MAX_RESPONSE_SNIPPET_LENGTH, MAX_FRAME_SNIPPET_LENGTH, } from "./limits.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/core",
-  "version": "1.6.43",
+  "version": "1.6.45",
   "description": "Homespun relay client: typed HTTP + WebSocket operations against a Homespun relay. Framework-free.",
   "license": "MIT",
   "type": "module",