@gjermundgaraba/clankercreds-api 0.0.0-stage → 0.5.0

package/dist/credentials.d.ts

@@ -0,0 +1,144 @@
+import { Schema } from "effect";
+export declare const GhCredential: Schema.Struct<{
+    readonly credential: Schema.String;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly type: Schema.Literal<"gh">;
+    readonly host: Schema.String;
+    readonly token: Schema.String;
+}>;
+export declare const ClaudeCredential: Schema.Struct<{
+    readonly credential: Schema.String;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly type: Schema.Literal<"claude">;
+    readonly token: Schema.String;
+}>;
+/**
+ * What Codex keeps in its `auth.json`, always written together: the three belong to one
+ * login. No refresh token: the client writes `<clientId>:<credential>:<key>` in its place.
+ */
+export declare const CodexLogin: Schema.Struct<{
+    readonly accessToken: Schema.String;
+    readonly idToken: Schema.String;
+    readonly accountId: Schema.String;
+}>;
+export type CodexLogin = typeof CodexLogin.Type;
+export declare const CodexCredential: Schema.Struct<{
+    readonly credential: Schema.String;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly accessToken: Schema.String;
+    readonly idToken: Schema.String;
+    readonly accountId: Schema.String;
+    readonly type: Schema.Literal<"codex">;
+}>;
+/**
+ * The access token `clankercreds token` answers pi with until it is near expiry: pi asks the
+ * command on every model call, and the command asks the service only after that.
+ */
+export declare const PiCredential: Schema.Struct<{
+    readonly credential: Schema.String;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly type: Schema.Literal<"pi">;
+    readonly accessToken: Schema.String;
+}>;
+/**
+ * A credential no machine places: an API key, or a Grok or Cursor login's access token, for
+ * a service such as clankerusage. `kind` is the credential's own, and any string, so a kind
+ * newer than the caller's contract still decodes. The client skips one a config names.
+ */
+export declare const TokenCredential: Schema.Struct<{
+    readonly credential: Schema.String;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly type: Schema.Literal<"token">;
+    readonly kind: Schema.String;
+    readonly token: Schema.String;
+}>;
+/**
+ * The service sends typed credentials, never file contents or paths, so it cannot write
+ * anything on a machine but what the client knows how to place. The cost is that a new
+ * tool, or a placement fix, needs a client release, which new machines install. Each entry
+ * names the credential it came from: a ChatGPT login arrives as a `codex` and a `pi` entry
+ * under the same name.
+ *
+ * Each machine keeps the client its setup installed, so old clients read what the service sends. A change
+ * an old client would get wrong is a new type name, which it skips: the decoder drops fields
+ * it does not know, so one ignoring `host` would place a GHE token as github.com's. A field
+ * an old client can safely ignore may be added; the service ships first, since a new client
+ * refuses an entry that lacks it.
+ */
+export declare const TypedCredential: Schema.Union<readonly [Schema.Struct<{
+    readonly credential: Schema.String;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly type: Schema.Literal<"gh">;
+    readonly host: Schema.String;
+    readonly token: Schema.String;
+}>, Schema.Struct<{
+    readonly credential: Schema.String;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly type: Schema.Literal<"claude">;
+    readonly token: Schema.String;
+}>, Schema.Struct<{
+    readonly credential: Schema.String;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly accessToken: Schema.String;
+    readonly idToken: Schema.String;
+    readonly accountId: Schema.String;
+    readonly type: Schema.Literal<"codex">;
+}>, Schema.Struct<{
+    readonly credential: Schema.String;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly type: Schema.Literal<"pi">;
+    readonly accessToken: Schema.String;
+}>, Schema.Struct<{
+    readonly credential: Schema.String;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly type: Schema.Literal<"token">;
+    readonly kind: Schema.String;
+    readonly token: Schema.String;
+}>]>;
+export type TypedCredential = typeof TypedCredential.Type;
+/** The types this build knows, derived from the union so there is one list. */
+export declare const knownTypes: ReadonlyArray<TypedCredential["type"]>;
+export declare const isKnownType: (type: string) => type is TypedCredential["type"];
+/**
+ * What the service may send that this client does not know yet. It decodes instead of
+ * failing, so the client can skip it with a warning. A known type that fails its own
+ * schema must not land here, or a broken credential would be placed as an empty one.
+ */
+export declare const UnknownCredential: Schema.Struct<{
+    readonly type: Schema.String;
+}>;
+/** Everything the caller asked for, sent in full on every sync. */
+export declare const Delivery: Schema.Struct<{
+    readonly credentials: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
+        readonly credential: Schema.String;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly type: Schema.Literal<"gh">;
+        readonly host: Schema.String;
+        readonly token: Schema.String;
+    }>, Schema.Struct<{
+        readonly credential: Schema.String;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly type: Schema.Literal<"claude">;
+        readonly token: Schema.String;
+    }>, Schema.Struct<{
+        readonly credential: Schema.String;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly accessToken: Schema.String;
+        readonly idToken: Schema.String;
+        readonly accountId: Schema.String;
+        readonly type: Schema.Literal<"codex">;
+    }>, Schema.Struct<{
+        readonly credential: Schema.String;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly type: Schema.Literal<"pi">;
+        readonly accessToken: Schema.String;
+    }>, Schema.Struct<{
+        readonly credential: Schema.String;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly type: Schema.Literal<"token">;
+        readonly kind: Schema.String;
+        readonly token: Schema.String;
+    }>]>, Schema.Struct<{
+        readonly type: Schema.String;
+    }>]>>;
+}>;

package/dist/credentials.js

@@ -0,0 +1,91 @@
+import { Schema } from "effect";
+import { Name } from "./shared.js";
+/**
+ * The credential an entry was delivered from, as it was asked for by name, and when what it
+ * carries expires, as ISO: a secret's as the operator entered it, a login's access token's
+ * own. Null never expires. A login delivered past it could not be renewed in time, as when its
+ * provider is away: sync again later. Whether it needs a new sign-in is the operator's to see.
+ */
+const fromCredential = { credential: Name, expiresAt: Schema.NullOr(Schema.String) };
+export const GhCredential = Schema.Struct({
+    type: Schema.Literal("gh"),
+    ...fromCredential,
+    host: Schema.String,
+    token: Schema.String,
+});
+export const ClaudeCredential = Schema.Struct({
+    type: Schema.Literal("claude"),
+    ...fromCredential,
+    token: Schema.String,
+});
+/**
+ * What Codex keeps in its `auth.json`, always written together: the three belong to one
+ * login. No refresh token: the client writes `<clientId>:<credential>:<key>` in its place.
+ */
+export const CodexLogin = Schema.Struct({
+    accessToken: Schema.String,
+    idToken: Schema.String,
+    accountId: Schema.String,
+});
+export const CodexCredential = Schema.Struct({
+    type: Schema.Literal("codex"),
+    ...fromCredential,
+    ...CodexLogin.fields,
+});
+/**
+ * The access token `clankercreds token` answers pi with until it is near expiry: pi asks the
+ * command on every model call, and the command asks the service only after that.
+ */
+export const PiCredential = Schema.Struct({
+    type: Schema.Literal("pi"),
+    ...fromCredential,
+    accessToken: Schema.String,
+});
+/**
+ * A credential no machine places: an API key, or a Grok or Cursor login's access token, for
+ * a service such as clankerusage. `kind` is the credential's own, and any string, so a kind
+ * newer than the caller's contract still decodes. The client skips one a config names.
+ */
+export const TokenCredential = Schema.Struct({
+    type: Schema.Literal("token"),
+    ...fromCredential,
+    kind: Schema.String,
+    token: Schema.String,
+});
+/**
+ * The service sends typed credentials, never file contents or paths, so it cannot write
+ * anything on a machine but what the client knows how to place. The cost is that a new
+ * tool, or a placement fix, needs a client release, which new machines install. Each entry
+ * names the credential it came from: a ChatGPT login arrives as a `codex` and a `pi` entry
+ * under the same name.
+ *
+ * Each machine keeps the client its setup installed, so old clients read what the service sends. A change
+ * an old client would get wrong is a new type name, which it skips: the decoder drops fields
+ * it does not know, so one ignoring `host` would place a GHE token as github.com's. A field
+ * an old client can safely ignore may be added; the service ships first, since a new client
+ * refuses an entry that lacks it.
+ */
+export const TypedCredential = Schema.Union([
+    GhCredential,
+    ClaudeCredential,
+    CodexCredential,
+    PiCredential,
+    TokenCredential,
+]);
+/** The types this build knows, derived from the union so there is one list. */
+export const knownTypes = TypedCredential.members.map((member) => member.fields.type.literal);
+export const isKnownType = (type) => knownTypes.some((known) => known === type);
+/**
+ * What the service may send that this client does not know yet. It decodes instead of
+ * failing, so the client can skip it with a warning. A known type that fails its own
+ * schema must not land here, or a broken credential would be placed as an empty one.
+ */
+export const UnknownCredential = Schema.Struct({
+    type: Schema.String.check(Schema.makeFilter((type) => !isKnownType(type), {
+        message: "a known credential type must match its schema",
+    })),
+});
+/** Everything the caller asked for, sent in full on every sync. */
+export const Delivery = Schema.Struct({
+    credentials: Schema.Array(Schema.Union([TypedCredential, UnknownCredential])),
+});

package/dist/machine.d.ts

@@ -0,0 +1,180 @@
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { ProviderUnavailable } from "@gjermundgaraba/clankerauth-sdk/errors";
+import { CurrentPrincipal } from "@gjermundgaraba/clankerauth-sdk/session";
+import { claimsOf, ClientId, CredentialKind, keyIdOf, Name, NeedsSignIn, NotFound, UpstreamUnavailable } from "./shared.ts";
+/**
+ * A credential the calling key may read, without its value. `kind` is any string, so a kind
+ * newer than the caller's contract does not fail the whole list.
+ */
+export declare const Grant: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.String;
+}>;
+/**
+ * What a machine key can do: read the credentials it is granted, by name, and nothing else.
+ * The caller names what it wants; the grants on the server decide whether it may. A machine
+ * is one caller; a service such as clankerusage, holding a key of its own, is another.
+ */
+export declare const Machine: readonly [Action.Action<"sync", Schema.Struct<{
+    readonly clientId: Schema.String;
+    readonly credentials: Schema.$Array<Schema.String>;
+}>, Schema.Struct<{
+    readonly credentials: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
+        readonly credential: Schema.String;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly type: Schema.Literal<"gh">;
+        readonly host: Schema.String;
+        readonly token: Schema.String;
+    }>, Schema.Struct<{
+        readonly credential: Schema.String;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly type: Schema.Literal<"claude">;
+        readonly token: Schema.String;
+    }>, Schema.Struct<{
+        readonly credential: Schema.String;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly accessToken: Schema.String;
+        readonly idToken: Schema.String;
+        readonly accountId: Schema.String;
+        readonly type: Schema.Literal<"codex">;
+    }>, Schema.Struct<{
+        readonly credential: Schema.String;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly type: Schema.Literal<"pi">;
+        readonly accessToken: Schema.String;
+    }>, Schema.Struct<{
+        readonly credential: Schema.String;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly type: Schema.Literal<"token">;
+        readonly kind: Schema.String;
+        readonly token: Schema.String;
+    }>]>, Schema.Struct<{
+        readonly type: Schema.String;
+    }>]>>;
+}>, readonly (typeof NotFound)[], false, typeof CurrentPrincipal>, Action.Action<"codexLogin", Schema.Struct<{
+    readonly clientId: Schema.String;
+    readonly credential: Schema.String;
+}>, Schema.Struct<{
+    readonly accessToken: Schema.String;
+    readonly idToken: Schema.String;
+    readonly accountId: Schema.String;
+}>, readonly (typeof NotFound | typeof NeedsSignIn | typeof UpstreamUnavailable)[], false, typeof CurrentPrincipal>, Action.Action<"listGrants", Schema.$Record<Schema.String, Schema.Never>, Schema.Struct<{
+    readonly credentials: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly kind: Schema.String;
+    }>>;
+}>, readonly never[], true, typeof CurrentPrincipal>];
+declare const CodexRefreshRejected_base: Schema.Class<CodexRefreshRejected, Schema.TaggedStruct<"CodexRefreshRejected", {
+    readonly error: Schema.Struct<{
+        readonly code: Schema.String;
+        readonly message: Schema.String;
+    }>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Codex treats a 401 as permanent and stops retrying; every other failure is transient.
+ * The codes are the ones Codex classifies: `refresh_token_invalidated` reads as revoked.
+ */
+export declare class CodexRefreshRejected extends CodexRefreshRejected_base {
+}
+declare const CodexRefreshUnavailable_base: Schema.Class<CodexRefreshUnavailable, Schema.TaggedStruct<"CodexRefreshUnavailable", {
+    readonly error: Schema.Struct<{
+        readonly code: Schema.String;
+        readonly message: Schema.String;
+    }>;
+}>, import("effect/Cause").YieldableError>;
+export declare class CodexRefreshUnavailable extends CodexRefreshUnavailable_base {
+}
+/**
+ * Codex's own refresh request, the one request whose shape is not ours. The refresh-token
+ * field carries `<clientId>:<credential>:<key>`, so the contract is public and its handler authenticates
+ * the key against the machine resource. The answer leaves `refresh_token` out, so Codex keeps the
+ * composite it has. Its input alone accepts fields it does not name: Codex may add one,
+ * and every other action refuses them.
+ */
+export declare const CodexRefresh: Action.Action<"codexRefresh", Schema.StructWithRest<Schema.Struct<{
+    readonly grant_type: Schema.Literal<"refresh_token">;
+    readonly refresh_token: Schema.String;
+    readonly client_id: Schema.optionalKey<Schema.String>;
+    readonly scope: Schema.optionalKey<Schema.String>;
+}>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>, Schema.Struct<{
+    readonly access_token: Schema.String;
+    readonly id_token: Schema.String;
+}>, readonly (typeof CodexRefreshRejected | typeof CodexRefreshUnavailable)[], false, typeof Action.Anyone>;
+/**
+ * `<clientId>:<credential>:<key>`: a key may be granted several ChatGPT logins, so the
+ * composite names the one Codex holds. Client ids and names exclude `:`, so the key is the rest.
+ */
+export declare const formatCodexRefreshToken: (clientId: string, credential: string, key: string) => string;
+export declare const parseCodexRefreshToken: (value: string) => {
+    clientId: string;
+    credential: string;
+    key: string;
+} | undefined;
+/**
+ * A machine key's bearer token on the public port, verified by the machine resource's own
+ * provider, which requires `clankercreds:machine`: a key without that scope is refused here.
+ */
+export declare const MachineLogin: Authentication.Descriptor<CurrentPrincipal, import("@gjermundgaraba/clankerauth-sdk/session").Caller, import("effect/http-api/HttpApiSecurity").Http, "clankercreds.machine", readonly [typeof ProviderUnavailable]>;
+/** Everything the public listener serves: the machine actions, and Codex's refresh beside them. */
+export declare const MachineHttp: ActionHttp.Binding<readonly [Action.Action<"sync", Schema.Struct<{
+    readonly clientId: Schema.String;
+    readonly credentials: Schema.$Array<Schema.String>;
+}>, Schema.Struct<{
+    readonly credentials: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
+        readonly credential: Schema.String;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly type: Schema.Literal<"gh">;
+        readonly host: Schema.String;
+        readonly token: Schema.String;
+    }>, Schema.Struct<{
+        readonly credential: Schema.String;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly type: Schema.Literal<"claude">;
+        readonly token: Schema.String;
+    }>, Schema.Struct<{
+        readonly credential: Schema.String;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly accessToken: Schema.String;
+        readonly idToken: Schema.String;
+        readonly accountId: Schema.String;
+        readonly type: Schema.Literal<"codex">;
+    }>, Schema.Struct<{
+        readonly credential: Schema.String;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly type: Schema.Literal<"pi">;
+        readonly accessToken: Schema.String;
+    }>, Schema.Struct<{
+        readonly credential: Schema.String;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly type: Schema.Literal<"token">;
+        readonly kind: Schema.String;
+        readonly token: Schema.String;
+    }>]>, Schema.Struct<{
+        readonly type: Schema.String;
+    }>]>>;
+}>, readonly (typeof NotFound)[], false, typeof CurrentPrincipal>, Action.Action<"codexLogin", Schema.Struct<{
+    readonly clientId: Schema.String;
+    readonly credential: Schema.String;
+}>, Schema.Struct<{
+    readonly accessToken: Schema.String;
+    readonly idToken: Schema.String;
+    readonly accountId: Schema.String;
+}>, readonly (typeof NotFound | typeof NeedsSignIn | typeof UpstreamUnavailable)[], false, typeof CurrentPrincipal>, Action.Action<"listGrants", Schema.$Record<Schema.String, Schema.Never>, Schema.Struct<{
+    readonly credentials: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly kind: Schema.String;
+    }>>;
+}>, readonly never[], true, typeof CurrentPrincipal>, Action.Action<"codexRefresh", Schema.StructWithRest<Schema.Struct<{
+    readonly grant_type: Schema.Literal<"refresh_token">;
+    readonly refresh_token: Schema.String;
+    readonly client_id: Schema.optionalKey<Schema.String>;
+    readonly scope: Schema.optionalKey<Schema.String>;
+}>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>, Schema.Struct<{
+    readonly access_token: Schema.String;
+    readonly id_token: Schema.String;
+}>, readonly (typeof CodexRefreshRejected | typeof CodexRefreshUnavailable)[], false, typeof Action.Anyone>], [], Authentication.Descriptor<CurrentPrincipal, import("@gjermundgaraba/clankerauth-sdk/session").Caller, import("effect/http-api/HttpApiSecurity").Http, "clankercreds.machine", readonly [typeof ProviderUnavailable]>>;
+export { claimsOf, ClientId, CredentialKind, keyIdOf, Name, NeedsSignIn, NotFound, UpstreamUnavailable, };
+export * from "./credentials.ts";

package/dist/machine.js

@@ -0,0 +1,102 @@
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { ProviderUnavailable } from "@gjermundgaraba/clankerauth-sdk/errors";
+import { CurrentPrincipal } from "@gjermundgaraba/clankerauth-sdk/session";
+import { CodexLogin, Delivery } from "./credentials.js";
+import { apiPath, claimsOf, ClientId, CredentialKind, keyIdOf, Name, NeedsSignIn, NotFound, UpstreamUnavailable, } from "./shared.js";
+/**
+ * A credential the calling key may read, without its value. `kind` is any string, so a kind
+ * newer than the caller's contract does not fail the whole list.
+ */
+export const Grant = Schema.Struct({ name: Name, kind: Schema.String });
+/**
+ * What a machine key can do: read the credentials it is granted, by name, and nothing else.
+ * The caller names what it wants; the grants on the server decide whether it may. A machine
+ * is one caller; a service such as clankerusage, holding a key of its own, is another.
+ */
+export const Machine = [
+    Action.make("sync", {
+        // Writes an audit row, served or refused; may save a refreshed login.
+        readOnly: false,
+        caller: CurrentPrincipal,
+        description: "Fetch the named credentials as typed entries, each with its expiry; a login near expiry is refreshed first. Refused whole when the calling key is not granted any one of them.",
+        input: Schema.Struct({ clientId: ClientId, credentials: Schema.Array(Name) }),
+        success: Delivery,
+        error: NotFound,
+    }),
+    Action.make("codexLogin", {
+        // May save a refreshed login; writes an audit row.
+        readOnly: false,
+        caller: CurrentPrincipal,
+        description: "The current login of a ChatGPT credential the calling key is granted, as the codex type carries it, refreshed first when it has expired.",
+        input: Schema.Struct({ clientId: ClientId, credential: Name }),
+        success: CodexLogin,
+        error: [NotFound, NeedsSignIn, UpstreamUnavailable],
+    }),
+    Action.make("listGrants", {
+        readOnly: true,
+        caller: CurrentPrincipal,
+        description: "The names and kinds of the credentials the calling key is granted, so a caller can offer them to pick from. Values are never returned.",
+        success: Schema.Struct({ credentials: Schema.Array(Grant) }),
+    }),
+];
+/**
+ * Codex treats a 401 as permanent and stops retrying; every other failure is transient.
+ * The codes are the ones Codex classifies: `refresh_token_invalidated` reads as revoked.
+ */
+export class CodexRefreshRejected extends Schema.TaggedError()("CodexRefreshRejected", { error: Schema.Struct({ code: Schema.String, message: Schema.String }) }, { httpApiStatus: 401 }) {
+}
+export class CodexRefreshUnavailable extends Schema.TaggedError()("CodexRefreshUnavailable", { error: Schema.Struct({ code: Schema.String, message: Schema.String }) }, { httpApiStatus: 503 }) {
+}
+/**
+ * Codex's own refresh request, the one request whose shape is not ours. The refresh-token
+ * field carries `<clientId>:<credential>:<key>`, so the contract is public and its handler authenticates
+ * the key against the machine resource. The answer leaves `refresh_token` out, so Codex keeps the
+ * composite it has. Its input alone accepts fields it does not name: Codex may add one,
+ * and every other action refuses them.
+ */
+export const CodexRefresh = Action.make("codexRefresh", {
+    // May save a refreshed login; a served login writes an audit row.
+    readOnly: false,
+    caller: Action.Anyone,
+    description: "Answer Codex's token refresh with the current tokens of the ChatGPT credential its composite names.",
+    input: Schema.StructWithRest(Schema.Struct({
+        grant_type: Schema.Literal("refresh_token"),
+        refresh_token: Schema.String,
+        client_id: Schema.optionalKey(Schema.String),
+        scope: Schema.optionalKey(Schema.String),
+    }), [Schema.Record(Schema.String, Schema.Json)]),
+    success: Schema.Struct({ access_token: Schema.String, id_token: Schema.String }),
+    error: [CodexRefreshRejected, CodexRefreshUnavailable],
+});
+/**
+ * `<clientId>:<credential>:<key>`: a key may be granted several ChatGPT logins, so the
+ * composite names the one Codex holds. Client ids and names exclude `:`, so the key is the rest.
+ */
+export const formatCodexRefreshToken = (clientId, credential, key) => `${clientId}:${credential}:${key}`;
+export const parseCodexRefreshToken = (value) => {
+    const first = value.indexOf(":");
+    const second = value.indexOf(":", first + 1);
+    if (first < 1 || second === -1 || second === value.length - 1)
+        return undefined;
+    const credential = value.slice(first + 1, second);
+    return Schema.is(Name)(credential)
+        ? { clientId: value.slice(0, first), credential, key: value.slice(second + 1) }
+        : undefined;
+};
+/**
+ * A machine key's bearer token on the public port, verified by the machine resource's own
+ * provider, which requires `clankercreds:machine`: a key without that scope is refused here.
+ */
+export const MachineLogin = Authentication.make("clankercreds.machine", CurrentPrincipal, {
+    error: ProviderUnavailable,
+});
+/** Everything the public listener serves: the machine actions, and Codex's refresh beside them. */
+export const MachineHttp = ActionHttp.make([...Machine, CodexRefresh], {
+    prefix: apiPath,
+    authentication: MachineLogin,
+});
+export { claimsOf, ClientId, CredentialKind, keyIdOf, Name, NeedsSignIn, NotFound, UpstreamUnavailable, };
+export * from "./credentials.js";

package/dist/shared.d.ts

@@ -0,0 +1,84 @@
+import { Schema } from "effect";
+import type { Caller } from "@gjermundgaraba/clankerauth-sdk/session";
+/** Every route is `POST /v1/<action>`: both bindings mount here, each on its own listener. */
+export declare const apiPath = "/v1";
+/**
+ * What a credential of the clankercreds resource may carry. `machine` admits the
+ * public actions and nothing else; `read` and `admin` admit the admin actions.
+ */
+export declare const scopes: {
+    readonly machine: "clankercreds:machine";
+    readonly read: "clankercreds:read";
+    readonly admin: "clankercreds:admin";
+};
+declare const NotFound_base: Schema.Class<NotFound, Schema.TaggedStruct<"NotFound", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * What was asked for does not exist: a key, credential or sign-in by that name, or a
+ * credential the calling machine key is not granted, which it is not told apart from one
+ * that does not exist.
+ */
+export declare class NotFound extends NotFound_base {
+}
+declare const Conflict_base: Schema.Class<Conflict, Schema.TaggedStruct<"Conflict", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The change collides with what is stored: a taken name, or a credential still in use. */
+export declare class Conflict extends Conflict_base {
+}
+declare const NeedsSignIn_base: Schema.Class<NeedsSignIn, Schema.TaggedStruct<"NeedsSignIn", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The login is dead, or was never completed. Only a new sign-in revives it. */
+export declare class NeedsSignIn extends NeedsSignIn_base {
+}
+declare const UpstreamUnavailable_base: Schema.Class<UpstreamUnavailable, Schema.TaggedStruct<"UpstreamUnavailable", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The provider could not be reached and no valid token is held. Waiting helps; retrying now does not. */
+export declare class UpstreamUnavailable extends UpstreamUnavailable_base {
+}
+/**
+ * Credential names: lowercase labels, because they are typed by hand and are
+ * identities. SQLite compares them case-sensitively, so mixed case would let `GitHub-Main`
+ * and `github-main` be two credentials.
+ */
+export declare const Name: Schema.String;
+/**
+ * What an operator stores a value for: a GitHub token, a Claude token, or `token`, any other
+ * service's API key, which a service such as clankerusage reads and no machine places.
+ */
+export declare const SecretKind: Schema.Literals<readonly ["gh", "claude", "token"]>;
+/**
+ * What a sign-in creates and the service keeps refreshed. The refresh token never leaves
+ * the service; only access tokens are delivered.
+ */
+export declare const LoginKind: Schema.Literals<readonly ["chatgpt", "grok", "cursor"]>;
+export declare const CredentialKind: Schema.Literals<readonly ["gh", "claude", "token", "chatgpt", "grok", "cursor"]>;
+/** A GitHub host, lowercase: it is written into `gh`'s and git's configuration as is. */
+export declare const Host: Schema.String;
+/**
+ * The machine's self-generated label. It identifies nothing; it only groups audit rows.
+ * It excludes `:` because the Codex refresh token is `<clientId>:<credential>:<key>`.
+ */
+export declare const ClientId: Schema.String;
+/**
+ * The one id the service records for a caller, whichever way clankerauth names it: the
+ * process itself, which no surface here admits, by its subject.
+ */
+export declare const keyIdOf: ({ actor, subject }: Caller) => string;
+/**
+ * The claims of a JWT, unverified: they are read for their timing, email and, in OpenAI's,
+ * account, never trusted for anything. Anything unreadable is simply no claims.
+ */
+export declare const claimsOf: (jwt: string) => {
+    exp: undefined;
+    email: undefined;
+    accountId: undefined;
+} | {
+    exp: number | undefined;
+    email: string | undefined;
+    accountId: string | undefined;
+};
+export {};