@w6w/sdk 0.3.0 → 0.5.0

package/dist/src/console/tenant-oauth-apps.js

@@ -0,0 +1,152 @@
+/**
+ * `client.console.tenantOAuthApps.*` — a tenant administrator's own OAuth
+ * client overrides (list, upsert, remove) for the apps their tenant connects
+ * to.
+ *
+ * **Studio-internal, not the published partner contract.** This namespace
+ * lives under the `console` subpath export (`@w6w/sdk/console`), excluded from
+ * `endpoints.json` and from the root barrel (`mod.ts`) — see `docs/console.md`.
+ * `@w6w/sdk`'s instance-state mechanism pin still applies here exactly as it
+ * does to every other namespace (`docs/implementation.md` §MECHANISM PIN —
+ * instance state, never globals): this class holds no state of its own beyond
+ * the injected host, so two clients in one process never share a credential.
+ *
+ * **The tenant is never a parameter here.** These three routes are scoped by
+ * the caller's own credential (the tenant claim on the bearer) plus a
+ * server-side tenant-admin check — unlike the operator family
+ * (`GET/PUT/DELETE /tenants/:id/oauth-app…`, `api/admin/tenants.ts:307-309`),
+ * which takes the tenant in the path and requires an operator. A `tenant`
+ * argument on any method below would be a tenant-selection affordance the
+ * server does not offer, so there is none.
+ *
+ * **Nothing here can read a client secret back.** {@linkcode
+ * TenantOAuthAppSummary} carries `hasClientSecret: boolean` and no secret
+ * field, mirroring the server's own summary projection
+ * (`packages/server/packages/db/repos/tenant_oauth_app.ts:26-37`, whose
+ * decrypting sibling `TenantOAuthApp` is entitled to exactly one caller in the
+ * BLL). That makes "no method on this namespace can ever resolve a stored
+ * secret" a compile-time fact rather than a runtime convention.
+ *
+ * **Response shapes are flat, no envelope key to peel with `unwrap()`** —
+ * mirroring `console/auth.ts:29-32` for this whole family. `list` returns the
+ * whole body deliberately, because `callbackUrl` rides beside `configs` and an
+ * `unwrap(res, "configs")` would silently drop it; `put` reaches one level in
+ * for `body.config`, which is the shape the server answers with (W4).
+ *
+ * **Wire shapes are planner pins, not reverse-engineered from a merged route.**
+ * `plan-B.md` § WIRE PINS W3–W5 fix `GET /tenant/oauth-apps`,
+ * `PUT /tenant/oauth-app/:app/:authKey` and
+ * `DELETE /tenant/oauth-app/:app/:authKey`; the tenant-scoped handlers are
+ * added by a sibling node on the server, against the same pins. The domain
+ * rules those handlers enforce already exist and are readable today in
+ * `packages/server/packages/bll/tenant-oauth-app.ts` — in particular
+ * `effectiveRow` (`:281-296`), which is what makes {@linkcode
+ * SetTenantOAuthAppInput}'s omission rule load-bearing rather than cosmetic.
+ * See {@linkcode SetTenantOAuthAppInput}.
+ *
+ * @module
+ */
+import { path } from "../http.js";
+/**
+ * Serialise {@linkcode SetTenantOAuthAppInput} for the wire: **only the keys
+ * actually present**, with `null` preserved as a real value.
+ *
+ * Written as four explicit `!== undefined` tests rather than a spread or an
+ * `Object.entries` loop, for two reasons. It keeps `undefined` off the wire
+ * without relying on `JSON.stringify` dropping it (a serializer that
+ * normalised `undefined` to `null` would silently wipe a stored credential —
+ * see {@linkcode SetTenantOAuthAppInput}), and it is an allowlist: a caller
+ * that widens the input type and passes `redirectUri` or `force` cannot get
+ * either onto the wire from here, at runtime as well as at compile time.
+ *
+ * @param input - The caller's partial update.
+ * @returns A body carrying exactly the keys `input` set.
+ */
+function toSetBody(input) {
+    const body = {};
+    if (input.clientId !== undefined)
+        body.clientId = input.clientId;
+    if (input.clientSecret !== undefined)
+        body.clientSecret = input.clientSecret;
+    if (input.extra !== undefined)
+        body.extra = input.extra;
+    if (input.disabled !== undefined)
+        body.disabled = input.disabled;
+    return body;
+}
+/**
+ * The `console.tenantOAuthApps` namespace on a `W6WClient` — the caller's own
+ * tenant, never a tenant of its choosing.
+ *
+ * @example
+ * ```ts
+ * const { configs, callbackUrl } = await client.console.tenantOAuthApps.list();
+ * // Register `callbackUrl` with the provider — never assemble it client-side.
+ * await client.console.tenantOAuthApps.put("sendgrid", "oauth2", { clientId: "abc" });
+ * await client.console.tenantOAuthApps.remove("sendgrid", "oauth2");
+ * ```
+ */
+export class TenantOAuthAppsApi {
+    #host;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host) {
+        this.#host = host;
+    }
+    /**
+     * List the caller's tenant's OAuth overrides, plus this host's callback URL.
+     *
+     * Returns the body VERBATIM rather than unwrapping `configs`: `callbackUrl`
+     * rides beside it and is the one value a caller cannot compute for itself.
+     *
+     * @returns Every override for this tenant, and the server-derived callback URL.
+     * @throws {ApiError} `403` when the caller does not administer its tenant.
+     */
+    async list() {
+        const res = await this.#host.request({
+            method: "GET",
+            path: "/tenant/oauth-apps",
+        });
+        return res.body;
+    }
+    /**
+     * Create or update one override, sending **only the fields `input` sets**.
+     *
+     * @param appId - The app id.
+     * @param authKey - The app manifest's `oauth2` auth method key.
+     * @param input - The fields to set; an omitted field is left untouched server-side.
+     * @returns The stored summary (the server answers `201 { config }`). Never carries a secret.
+     * @throws {ApiError} `403` when the caller does not administer its tenant;
+     * `404 unknown_app` when the app does not exist or does not support a tenant
+     * OAuth client; `400 invalid_config`/`invalid_redirect_uri` when the merged
+     * row would be an enabled override missing a required field.
+     */
+    async put(appId, authKey, input) {
+        const res = await this.#host.request({
+            method: "PUT",
+            path: path `/tenant/oauth-app/${appId}/${authKey}`,
+            body: toSetBody(input),
+        });
+        return res.body.config;
+    }
+    /**
+     * Remove one override; the tenant falls back to the host's own OAuth client.
+     *
+     * Resolves `void`, discarding the server's uninformative `{ok: true}` —
+     * mirroring `projects.delete`/`schedules.delete`, not `apps.delete` (which
+     * keeps a genuinely informative count).
+     *
+     * @param appId - The app id.
+     * @param authKey - The app manifest's `oauth2` auth method key.
+     * @throws {ApiError} `403` when the caller does not administer its tenant;
+     * `404 unknown_tenant_oauth_app` when there is no override to remove.
+     */
+    async remove(appId, authKey) {
+        await this.#host.request({
+            method: "DELETE",
+            path: path `/tenant/oauth-app/${appId}/${authKey}`,
+        });
+    }
+}
+//# sourceMappingURL=tenant-oauth-apps.js.map

package/dist/src/console/tenant-oauth-apps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-oauth-apps.js","sourceRoot":"","sources":["../../../src/console/tenant-oauth-apps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,EAAqB,IAAI,EAAuB,MAAM,YAAY,CAAC;AAyF1E;;;;;;;;;;;;;;GAcG;AACH,SAAS,SAAS,CAAC,KAA6B;IAC9C,MAAM,IAAI,GAA4B,EAAE,CAAC;IACzC,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS;QAAE,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IACjE,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;QAAE,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;IAC7E,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;QAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IACxD,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS;QAAE,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IACjE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,kBAAkB;IACpB,KAAK,CAAsB;IAEpC;;OAEG;IACH,YAAY,IAAyB;QACnC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAA0B;YAC5D,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,oBAAoB;SAC3B,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,GAAG,CACP,KAAa,EACb,OAAe,EACf,KAA6B;QAE7B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAoC;YACtE,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,IAAI,CAAA,qBAAqB,KAAK,IAAI,OAAO,EAAE;YACjD,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC;SACvB,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC;IACzB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,OAAe;QACzC,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAChC,MAAM,EAAE,QAAQ;YAChB,IAAI,EAAE,IAAI,CAAA,qBAAqB,KAAK,IAAI,OAAO,EAAE;SAClD,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/src/console/tokens.d.ts

@@ -0,0 +1,159 @@
+/**
+ * `client.console.tokens.*` — long-lived API tokens for programmatic access
+ * (list, create, disable, enable, revoke), relocated from the studio's own
+ * API client.
+ *
+ * **Studio-internal, not the published partner contract.** This namespace
+ * lives under the `console` subpath export (`@w6w/sdk/console`), excluded from
+ * `endpoints.json` and from the root barrel (`mod.ts`) — see `docs/console.md`
+ * and HITL-1 in this task's contract. `@w6w/sdk`'s instance-state mechanism
+ * pin still applies here exactly as it does to every other namespace
+ * (`docs/implementation.md` §MECHANISM PIN — instance state, never globals):
+ * this class holds no state of its own beyond the injected host, so two
+ * clients in one process never share a credential.
+ *
+ * **`create`'s plaintext-once invariant is the mechanism this whole domain
+ * rests on.** `POST /tokens` is the ONLY response in this entire package that
+ * returns a token's plaintext — there is no reveal-later route. That is why
+ * {@linkcode CreateTokenResponse} is a SEPARATE type from {@linkcode ApiToken}
+ * rather than an optional `secret?` field bolted onto it: `ApiToken` — the
+ * return type of every other method here (`list`/`disable`/`enable`/`revoke`)
+ * — structurally cannot carry a `secret`, which makes "nothing reachable
+ * through those four methods can ever carry a secret" a compile-time fact,
+ * not a runtime convention. The server's own `toWire()` doc comment states
+ * the same invariant server-side: "never carries the secret, the hash, or
+ * internals."
+ *
+ * Five methods relocate from the studio's own `// API tokens` comment block
+ * (`packages/studio/src/api/client.ts:280-303` on the current merged tree) —
+ * field-for-field, not redesigned. Studio never sends `account` or
+ * `includeRevoked` on `list` (the server's list default already excludes
+ * revoked) — per HITL-4's own philosophy ("SDK completeness tracks studio's
+ * actual call surface, not the server's full route surface"), neither is
+ * added here.
+ *
+ * None of these methods take a `project` scoping parameter — tokens are
+ * account-scoped via the credential alone — so `TokensHost` needs only the
+ * transport, mirroring `VarsHost`/`ConnectionsHost`, not `DocumentsHost`.
+ *
+ * @module
+ */
+import { type HttpResponse, type RequestOptions } from "../http.ts";
+/**
+ * The slice of `W6WClient` this namespace needs: the transport, and nothing
+ * else. Structural rather than a concrete client type, so the namespace stays
+ * independently constructible in a test and this module never imports the
+ * client back — mirrors `ConnectionsHost` in `./connections.ts`.
+ */
+export interface TokensHost {
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/** Lifecycle status of an API token. `revoked` is terminal; `disabled` is reversible. */
+export type ApiTokenStatus = "active" | "disabled" | "revoked";
+/**
+ * A long-lived API token for programmatic access — distinct from the studio's
+ * own session JWT. **Never carries `secret`** — the server's `toWire()` never
+ * puts it on the wire for this shape, and neither does this type. The
+ * plaintext is reachable only once, from {@linkcode CreateTokenResponse}.
+ */
+export interface ApiToken {
+    /** Server-issued id. */
+    id: string;
+    /** The account this token authenticates as. */
+    account: string;
+    /** Caller-chosen label. */
+    name: string;
+    /** Lifecycle status. */
+    status: ApiTokenStatus;
+    /** ISO-8601 timestamp. */
+    createdAt: string;
+    /** ISO-8601 timestamp. */
+    updatedAt: string;
+    /** ISO-8601 timestamp of revocation, or `null` while active/disabled. */
+    revokedAt: string | null;
+}
+/**
+ * `create`'s result — the token's metadata plus its plaintext secret, shown
+ * exactly ONCE. Defined as a type **separate** from {@linkcode ApiToken}, not
+ * an optional field on it — see this module's header comment for why that
+ * separation is load-bearing rather than a style choice. There is no
+ * reveal-later route: if the caller does not capture `secret` here, it is
+ * gone.
+ */
+export interface CreateTokenResponse {
+    /** The created token's metadata. Never carries the secret. */
+    token: ApiToken;
+    /** The plaintext credential. Shown exactly once — never logged, never re-fetchable. */
+    secret: string;
+}
+/**
+ * The `console.tokens` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const tokens = await client.console.tokens.list();
+ * const { token, secret } = await client.console.tokens.create("ci-deploy");
+ * console.log(secret); // shown exactly once — capture it now or it is gone
+ * await client.console.tokens.disable(token.id);
+ * await client.console.tokens.enable(token.id);
+ * await client.console.tokens.revoke(token.id);
+ * ```
+ */
+export declare class TokensApi {
+    #private;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host: TokensHost);
+    /**
+     * List the account's tokens. Excludes revoked tokens (the server's default);
+     * this method does not expose a parameter to include them, matching
+     * studio's own call surface.
+     *
+     * @returns The tokens, unwrapped from the `tokens` envelope. Never carries `secret`.
+     */
+    list(): Promise<ApiToken[]>;
+    /**
+     * Create a token. **Returns the plaintext secret exactly once** — there is
+     * no reveal-later route, so a caller that does not capture it here has
+     * permanently lost it.
+     *
+     * **No envelope key to peel — the whole body IS `{token, secret}`.** Typed
+     * directly as `request<CreateTokenResponse>(...)`, returning `res.body`,
+     * mirroring `console.connections.test`'s/`console.reliability.list`'s
+     * established "no envelope key" pattern. `unwrap()` is deliberately not
+     * called here: there is no single key to unwrap.
+     *
+     * @param name - Caller-chosen label.
+     * @returns The created token's metadata plus its one-time plaintext secret.
+     * @throws {ApiError} `400 invalid_name`.
+     */
+    create(name: string): Promise<CreateTokenResponse>;
+    /**
+     * Disable a token. Reversible — see {@linkcode enable}.
+     *
+     * @param id - The token id.
+     * @returns The updated token, unwrapped from the `token` envelope. Never carries `secret`.
+     * @throws {ApiError} `404 unknown_token`/`unknown_account`.
+     */
+    disable(id: string): Promise<ApiToken>;
+    /**
+     * Re-enable a disabled token.
+     *
+     * @param id - The token id.
+     * @returns The updated token, unwrapped from the `token` envelope. Never carries `secret`.
+     * @throws {ApiError} `404 unknown_token`/`unknown_account`; `409 invalid_transition` when the
+     * token is revoked (revoke is terminal).
+     */
+    enable(id: string): Promise<ApiToken>;
+    /**
+     * Revoke a token. Terminal — a revoked token cannot be re-enabled.
+     *
+     * @param id - The token id.
+     * @returns The updated token, unwrapped from the `token` envelope. Never carries `secret`.
+     * @throws {ApiError} `404 unknown_token`/`unknown_account`.
+     */
+    revoke(id: string): Promise<ApiToken>;
+}
+//# sourceMappingURL=tokens.d.ts.map

package/dist/src/console/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../../src/console/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAQ,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAG1E;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED,yFAAyF;AACzF,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,MAAM,EAAE,cAAc,CAAC;IACvB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,KAAK,EAAE,QAAQ,CAAC;IAChB,uFAAuF;IACvF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,SAAS;;IAGpB;;OAEG;gBACS,IAAI,EAAE,UAAU;IAI5B;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAKjC;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IASxD;;;;;;OAMG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAS5C;;;;;;;OAOG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAS3C;;;;;;OAMG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;CAQ5C"}

package/dist/src/console/tokens.js

@@ -0,0 +1,145 @@
+/**
+ * `client.console.tokens.*` — long-lived API tokens for programmatic access
+ * (list, create, disable, enable, revoke), relocated from the studio's own
+ * API client.
+ *
+ * **Studio-internal, not the published partner contract.** This namespace
+ * lives under the `console` subpath export (`@w6w/sdk/console`), excluded from
+ * `endpoints.json` and from the root barrel (`mod.ts`) — see `docs/console.md`
+ * and HITL-1 in this task's contract. `@w6w/sdk`'s instance-state mechanism
+ * pin still applies here exactly as it does to every other namespace
+ * (`docs/implementation.md` §MECHANISM PIN — instance state, never globals):
+ * this class holds no state of its own beyond the injected host, so two
+ * clients in one process never share a credential.
+ *
+ * **`create`'s plaintext-once invariant is the mechanism this whole domain
+ * rests on.** `POST /tokens` is the ONLY response in this entire package that
+ * returns a token's plaintext — there is no reveal-later route. That is why
+ * {@linkcode CreateTokenResponse} is a SEPARATE type from {@linkcode ApiToken}
+ * rather than an optional `secret?` field bolted onto it: `ApiToken` — the
+ * return type of every other method here (`list`/`disable`/`enable`/`revoke`)
+ * — structurally cannot carry a `secret`, which makes "nothing reachable
+ * through those four methods can ever carry a secret" a compile-time fact,
+ * not a runtime convention. The server's own `toWire()` doc comment states
+ * the same invariant server-side: "never carries the secret, the hash, or
+ * internals."
+ *
+ * Five methods relocate from the studio's own `// API tokens` comment block
+ * (`packages/studio/src/api/client.ts:280-303` on the current merged tree) —
+ * field-for-field, not redesigned. Studio never sends `account` or
+ * `includeRevoked` on `list` (the server's list default already excludes
+ * revoked) — per HITL-4's own philosophy ("SDK completeness tracks studio's
+ * actual call surface, not the server's full route surface"), neither is
+ * added here.
+ *
+ * None of these methods take a `project` scoping parameter — tokens are
+ * account-scoped via the credential alone — so `TokensHost` needs only the
+ * transport, mirroring `VarsHost`/`ConnectionsHost`, not `DocumentsHost`.
+ *
+ * @module
+ */
+import { path } from "../http.js";
+import { unwrap } from "../types.js";
+/**
+ * The `console.tokens` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const tokens = await client.console.tokens.list();
+ * const { token, secret } = await client.console.tokens.create("ci-deploy");
+ * console.log(secret); // shown exactly once — capture it now or it is gone
+ * await client.console.tokens.disable(token.id);
+ * await client.console.tokens.enable(token.id);
+ * await client.console.tokens.revoke(token.id);
+ * ```
+ */
+export class TokensApi {
+    #host;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host) {
+        this.#host = host;
+    }
+    /**
+     * List the account's tokens. Excludes revoked tokens (the server's default);
+     * this method does not expose a parameter to include them, matching
+     * studio's own call surface.
+     *
+     * @returns The tokens, unwrapped from the `tokens` envelope. Never carries `secret`.
+     */
+    async list() {
+        const res = await this.#host.request({ method: "GET", path: "/tokens" });
+        return unwrap(res, "tokens");
+    }
+    /**
+     * Create a token. **Returns the plaintext secret exactly once** — there is
+     * no reveal-later route, so a caller that does not capture it here has
+     * permanently lost it.
+     *
+     * **No envelope key to peel — the whole body IS `{token, secret}`.** Typed
+     * directly as `request<CreateTokenResponse>(...)`, returning `res.body`,
+     * mirroring `console.connections.test`'s/`console.reliability.list`'s
+     * established "no envelope key" pattern. `unwrap()` is deliberately not
+     * called here: there is no single key to unwrap.
+     *
+     * @param name - Caller-chosen label.
+     * @returns The created token's metadata plus its one-time plaintext secret.
+     * @throws {ApiError} `400 invalid_name`.
+     */
+    async create(name) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: "/tokens",
+            body: { name },
+        });
+        return res.body;
+    }
+    /**
+     * Disable a token. Reversible — see {@linkcode enable}.
+     *
+     * @param id - The token id.
+     * @returns The updated token, unwrapped from the `token` envelope. Never carries `secret`.
+     * @throws {ApiError} `404 unknown_token`/`unknown_account`.
+     */
+    async disable(id) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: path `/tokens/${id}/disable`,
+            body: {},
+        });
+        return unwrap(res, "token");
+    }
+    /**
+     * Re-enable a disabled token.
+     *
+     * @param id - The token id.
+     * @returns The updated token, unwrapped from the `token` envelope. Never carries `secret`.
+     * @throws {ApiError} `404 unknown_token`/`unknown_account`; `409 invalid_transition` when the
+     * token is revoked (revoke is terminal).
+     */
+    async enable(id) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: path `/tokens/${id}/enable`,
+            body: {},
+        });
+        return unwrap(res, "token");
+    }
+    /**
+     * Revoke a token. Terminal — a revoked token cannot be re-enabled.
+     *
+     * @param id - The token id.
+     * @returns The updated token, unwrapped from the `token` envelope. Never carries `secret`.
+     * @throws {ApiError} `404 unknown_token`/`unknown_account`.
+     */
+    async revoke(id) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: path `/tokens/${id}/revoke`,
+            body: {},
+        });
+        return unwrap(res, "token");
+    }
+}
+//# sourceMappingURL=tokens.js.map

package/dist/src/console/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../../src/console/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAqB,IAAI,EAAuB,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAsDrC;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,SAAS;IACX,KAAK,CAAa;IAE3B;;OAEG;IACH,YAAY,IAAgB;QAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QAClF,OAAO,MAAM,CAAa,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAsB;YACxD,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,EAAE,IAAI,EAAE;SACf,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,EAAU;QACtB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAA,WAAW,EAAE,UAAU;YACjC,IAAI,EAAE,EAAE;SACT,CAAC,CAAC;QACH,OAAO,MAAM,CAAW,GAAG,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAA,WAAW,EAAE,SAAS;YAChC,IAAI,EAAE,EAAE;SACT,CAAC,CAAC;QACH,OAAO,MAAM,CAAW,GAAG,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAA,WAAW,EAAE,SAAS;YAChC,IAAI,EAAE,EAAE;SACT,CAAC,CAAC;QACH,OAAO,MAAM,CAAW,GAAG,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;CACF"}

package/dist/src/console/vault.d.ts

@@ -0,0 +1,188 @@
+/**
+ * `client.console.vault.*` — the write-only secret store (list, get, create,
+ * update, delete, seal), relocated from the studio's own API client.
+ *
+ * **Studio-internal, not the published partner contract.** This namespace
+ * lives under the `console` subpath export (`@w6w/sdk/console`), excluded from
+ * `endpoints.json` and from the root barrel (`mod.ts`) — see `docs/console.md`
+ * and HITL-1 in this task's contract. `@w6w/sdk`'s instance-state mechanism
+ * pin still applies here exactly as it does to every other namespace
+ * (`docs/implementation.md` §MECHANISM PIN — instance state, never globals):
+ * this class holds no state of its own beyond the injected host, so two
+ * clients in one process never share a credential.
+ *
+ * **Write-only, no-plaintext-in-responses is the invariant this whole domain
+ * rests on** (`packages/server/packages/api/admin/vault.ts:1-21`'s own header
+ * comment: "plaintext values NEVER appear in a response"). `list`/`get` never
+ * carry `value` — by the server's wire contract itself, not by client
+ * discipline — which is why {@linkcode VaultSecretSummary} has no `value`
+ * field. `create`/`update` forward `value` verbatim to *write* it, and it is
+ * simply never echoed back. `seal` is the one deliberate exception, and even
+ * there it never returns the plaintext: it answers with a ciphertext envelope
+ * (`SecretValue`) — an encrypt-only oracle with no matching decrypt route, so
+ * an authed caller learns nothing they didn't already provide.
+ *
+ * Six methods relocate from the studio's own `// Vault` comment block
+ * (`packages/studio/src/api/client.ts:257-278` on the current merged tree) —
+ * field-for-field, not redesigned.
+ *
+ * `value` is opaque — forwarded verbatim on `create`/`update`/`seal`, never
+ * inspected, logged, or transformed. This is a security-adjacent discipline,
+ * not a style note: the whole point of this field is a caller-opaque secret
+ * payload.
+ *
+ * None of these methods take a `project` scoping parameter — vault secrets
+ * are subject-scoped like `vars`, not project-scoped — so `VaultHost` needs
+ * only the transport, mirroring `VarsHost`/`ConnectionsHost`, not
+ * `DocumentsHost`.
+ *
+ * @module
+ */
+import { type HttpResponse, type RequestOptions } from "../http.ts";
+/**
+ * The slice of `W6WClient` this namespace needs: the transport, and nothing
+ * else. Structural rather than a concrete client type, so the namespace stays
+ * independently constructible in a test and this module never imports the
+ * client back — mirrors `ConnectionsHost` in `./connections.ts`.
+ */
+export interface VaultHost {
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/**
+ * Public projection of a stored vault secret. **`value` is deliberately
+ * absent** — the server never puts a secret's plaintext on the wire for
+ * `list`/`get`/`create`/`update`, and declaring the field here would promise a
+ * caller something that can never arrive.
+ */
+export interface VaultSecretSummary {
+    /** Server-issued id, `sec_…`. */
+    id: string;
+    /** Caller-chosen name, matching `^[a-z_][a-z0-9_]*$`. */
+    name: string;
+    /** Free-text description; `""` when unset. */
+    description: string;
+    /** ISO-8601 timestamp. */
+    createdAt: string;
+    /** ISO-8601 timestamp. */
+    updatedAt: string;
+}
+/**
+ * An at-rest ciphertext envelope for one ad-hoc secret value, produced by
+ * {@linkcode VaultApi.seal}. Field-for-field identical to
+ * `packages/ui/src/types.ts`'s `SecretValue` shape, defined locally here
+ * rather than imported from `@w6w/ui` — this SDK has no dependency on
+ * `packages/ui` and must not gain one (wrong dependency direction for a
+ * published SDK). TypeScript's structural typing makes this value satisfy
+ * `@w6w/ui`'s `ExpressionOptions.sealSecret` prop shape at a studio call site
+ * with no shared import needed.
+ */
+export interface SecretValue {
+    type: "secret";
+    /** Base64-encoded ciphertext. */
+    ciphertext: string;
+    /** Base64-encoded initialization vector. */
+    iv: string;
+}
+/**
+ * The `console.vault` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const secrets = await client.console.vault.list();
+ * const created = await client.console.vault.create({ name: "openai_key", value: "sk-…" });
+ * await client.console.vault.update(created.id, { description: "Prod key" });
+ * const sealed = await client.console.vault.seal("sk-live-…");
+ * await client.console.vault.delete(created.id);
+ * ```
+ */
+export declare class VaultApi {
+    #private;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host: VaultHost);
+    /**
+     * List the account's vault secrets.
+     *
+     * @returns The secrets, unwrapped from the `secrets` envelope. Never
+     * carries `value`.
+     */
+    list(): Promise<VaultSecretSummary[]>;
+    /**
+     * Fetch one secret's metadata.
+     *
+     * **Zero studio callers today** — built for SDK completeness only. No 404
+     * special-casing — propagates as `ApiError` like every other "get" in this
+     * package except `console.schedules.get`, which has its own documented,
+     * unrelated exception.
+     *
+     * @param id - The `sec_…` id.
+     * @returns The secret, unwrapped from the `secret` envelope. Never carries `value`.
+     * @throws {ApiError} `404 unknown_secret` when there is no such id.
+     */
+    get(id: string): Promise<VaultSecretSummary>;
+    /**
+     * Create a secret.
+     *
+     * `value` is opaque — forwarded verbatim, never inspected, logged, or
+     * transformed.
+     *
+     * @param body - `name` (unique, matches `^[a-z_][a-z0-9_]*$`), `value` (the
+     * plaintext to store), and an optional `description`.
+     * @returns The created secret, unwrapped from the `secret` envelope (the
+     * server answers `201`). Never carries `value`.
+     * @throws {ApiError} `400 invalid_name`/`invalid_value`/`invalid_description`; `409 secret_exists`.
+     */
+    create(body: {
+        name: string;
+        value: string;
+        description?: string;
+    }): Promise<VaultSecretSummary>;
+    /**
+     * Update a secret: replace its value and/or its description.
+     *
+     * `value` is opaque — forwarded verbatim, never inspected, logged, or
+     * transformed, same discipline as {@linkcode create}.
+     *
+     * @param id - The `sec_…` id.
+     * @param body - `value` and/or `description`, forwarded verbatim.
+     * @returns The updated secret, unwrapped from the `secret` envelope. Never carries `value`.
+     * @throws {ApiError} `400 invalid_value`/`invalid_description`; `404 unknown_secret`.
+     */
+    update(id: string, body: {
+        value?: string;
+        description?: string;
+    }): Promise<VaultSecretSummary>;
+    /**
+     * Delete a secret.
+     *
+     * Returns nothing: the server's `{ok: true}` carries no information a
+     * caller can use, mirroring `console.projects.delete`/
+     * `console.schedules.delete`/`console.connections.delete` in this same
+     * package (NOT `console.apps.delete`, which is the one documented
+     * exception) — vault delete has no such value to preserve.
+     *
+     * @param id - The `sec_…` id.
+     * @throws {ApiError} `404 unknown_secret` when there is no such id.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Encrypt an ad-hoc secret value into an at-rest ciphertext envelope,
+     * without storing it.
+     *
+     * **An encrypt-only oracle — there is no matching decrypt route.** The
+     * server's own header comment states the security property directly: "an
+     * authed caller learns nothing they didn't provide." `value` is opaque —
+     * forwarded verbatim, never inspected, logged, or transformed. **No
+     * envelope key to peel on the request side** — the body IS `{ value }` —
+     * but the *response* IS enveloped under `sealed`, unlike `console.
+     * connections.test`'s/`console.reliability.list`'s whole-body responses.
+     *
+     * @param value - The plaintext to seal. Never logged, never echoed back.
+     * @returns The ciphertext envelope, unwrapped from the `sealed` envelope.
+     * @throws {ApiError} `400 invalid_value` when `value` is empty.
+     */
+    seal(value: string): Promise<SecretValue>;
+}
+//# sourceMappingURL=vault.d.ts.map

package/dist/src/console/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../../src/console/vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAQ,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAG1E;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,QAAQ;;IAGnB;;OAEG;gBACS,IAAI,EAAE,SAAS;IAI3B;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAK3C;;;;;;;;;;;OAWG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAKlD;;;;;;;;;;;OAWG;IACG,MAAM,CACV,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1D,OAAO,CAAC,kBAAkB,CAAC;IAK9B;;;;;;;;;;OAUG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7C,OAAO,CAAC,kBAAkB,CAAC;IAS9B;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC;;;;;;;;;;;;;;;OAeG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAQhD"}