@gjermundgaraba/clankercreds-api 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gjermund Garaba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/admin.d.ts

@@ -0,0 +1,394 @@
+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 { Conflict, CredentialKind, LoginKind, Name, NeedsSignIn, NotFound, scopes, SecretKind, UpstreamUnavailable } from "./shared.ts";
+/** A stored secret's state. The value itself is never read back out. */
+export declare const SecretStatus: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["gh", "claude", "token"]>;
+    /** The host a `gh` token is for; null for every other kind. */
+    readonly host: Schema.NullOr<Schema.String>;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+}>;
+/** A login's state. It exists from the first completed sign-in on. */
+export declare const LoginStatus: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["chatgpt", "grok", "cursor"]>;
+    readonly needsSignIn: Schema.Boolean;
+    readonly email: Schema.NullOr<Schema.String>;
+    /** The ChatGPT account a ChatGPT login is for; null for every other kind. */
+    readonly accountId: Schema.NullOr<Schema.String>;
+    readonly accessExpiresAt: Schema.String;
+    readonly lastRefreshAt: Schema.String;
+    readonly lastError: Schema.NullOr<Schema.String>;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+}>;
+export declare const CredentialStatus: Schema.Union<readonly [Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["gh", "claude", "token"]>;
+    /** The host a `gh` token is for; null for every other kind. */
+    readonly host: Schema.NullOr<Schema.String>;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+}>, Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["chatgpt", "grok", "cursor"]>;
+    readonly needsSignIn: Schema.Boolean;
+    readonly email: Schema.NullOr<Schema.String>;
+    /** The ChatGPT account a ChatGPT login is for; null for every other kind. */
+    readonly accountId: Schema.NullOr<Schema.String>;
+    readonly accessExpiresAt: Schema.String;
+    readonly lastRefreshAt: Schema.String;
+    readonly lastError: Schema.NullOr<Schema.String>;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+}>]>;
+export type CredentialStatus = typeof CredentialStatus.Type;
+/**
+ * A machine key and the credentials it may read. A machine names which of them it syncs; a
+ * replacement key is granted the same ones and overlaps the old key until that is removed.
+ * A key may be granted several credentials of one kind: several accounts of a provider.
+ */
+export declare const KeyInfo: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly credentials: Schema.$Array<Schema.String>;
+}>;
+/**
+ * A pending Claude sign-in: approve at `authorizeUrl`, then hand the code the callback page
+ * shows to `completeClaudeSignIn`. The code is useless without the verifier the service holds.
+ */
+export declare const ClaudeSignIn: Schema.Struct<{
+    readonly signInId: Schema.String;
+    readonly credential: Schema.String;
+    readonly authorizeUrl: Schema.String;
+    readonly expiresAt: Schema.String;
+}>;
+declare const SignInRefused_base: Schema.Class<SignInRefused, Schema.TaggedStruct<"SignInRefused", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A Claude sign-in's code was not taken: it is not this sign-in's, or Anthropic refused it.
+ * The sign-in stays open until it expires, for the code again or a new one from its
+ * `authorizeUrl`. An approval that left out a scope the token needs ends it: start again.
+ */
+export declare class SignInRefused extends SignInRefused_base {
+}
+/**
+ * A login's sign-in: open `verificationUrl` and approve, entering `userCode` where the
+ * provider asks for one. Cursor's link carries everything and has no code.
+ */
+export declare const SignInState: Schema.Struct<{
+    readonly signInId: Schema.String;
+    readonly credential: Schema.String;
+    readonly kind: Schema.Literals<readonly ["chatgpt", "grok", "cursor"]>;
+    readonly status: Schema.Literals<readonly ["pending", "complete", "failed", "expired"]>;
+    readonly userCode: Schema.NullOr<Schema.String>;
+    readonly verificationUrl: Schema.String;
+    readonly expiresAt: Schema.String;
+    readonly message: Schema.optionalKey<Schema.String>;
+}>;
+/** Credentials by name: rows outlive what they name, and stay findable. */
+export declare const AuditEntry: Schema.Struct<{
+    readonly id: Schema.Int;
+    readonly at: Schema.String;
+    readonly actorKind: Schema.Literals<readonly ["machine", "admin", "system"]>;
+    readonly keyId: Schema.NullOr<Schema.String>;
+    readonly clientId: Schema.NullOr<Schema.String>;
+    readonly action: Schema.String;
+    readonly credential: Schema.NullOr<Schema.String>;
+    readonly remoteAddr: Schema.NullOr<Schema.String>;
+    readonly detail: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+/** Every filter is optional; the page size defaults on the service. */
+export declare const AuditQuery: Schema.Struct<{
+    readonly limit: Schema.optionalKey<Schema.Int>;
+    readonly before: Schema.optionalKey<Schema.Int>;
+    readonly action: Schema.optionalKey<Schema.String>;
+    readonly credential: Schema.optionalKey<Schema.String>;
+    readonly keyId: Schema.optionalKey<Schema.String>;
+    readonly clientId: Schema.optionalKey<Schema.String>;
+}>;
+/**
+ * A read whose code or link signs an account in: exported so the server's authorization
+ * rule can name it.
+ */
+export declare const GetSignIn: Action.Action<"getSignIn", Schema.Struct<{
+    readonly signInId: Schema.String;
+}>, Schema.Struct<{
+    readonly signInId: Schema.String;
+    readonly credential: Schema.String;
+    readonly kind: Schema.Literals<readonly ["chatgpt", "grok", "cursor"]>;
+    readonly status: Schema.Literals<readonly ["pending", "complete", "failed", "expired"]>;
+    readonly userCode: Schema.NullOr<Schema.String>;
+    readonly verificationUrl: Schema.String;
+    readonly expiresAt: Schema.String;
+    readonly message: Schema.optionalKey<Schema.String>;
+}>, readonly (typeof NotFound)[], true, typeof CurrentPrincipal>;
+/** Everything an operator does; which scope each needs is the server's authorization rule. */
+export declare const Admin: readonly [Action.Action<"listCredentials", Schema.$Record<Schema.String, Schema.Never>, Schema.Struct<{
+    readonly credentials: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly name: Schema.String;
+        readonly kind: Schema.Literals<readonly ["gh", "claude", "token"]>;
+        /** The host a `gh` token is for; null for every other kind. */
+        readonly host: Schema.NullOr<Schema.String>;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly createdAt: Schema.String;
+        readonly updatedAt: Schema.String;
+    }>, Schema.Struct<{
+        readonly name: Schema.String;
+        readonly kind: Schema.Literals<readonly ["chatgpt", "grok", "cursor"]>;
+        readonly needsSignIn: Schema.Boolean;
+        readonly email: Schema.NullOr<Schema.String>;
+        /** The ChatGPT account a ChatGPT login is for; null for every other kind. */
+        readonly accountId: Schema.NullOr<Schema.String>;
+        readonly accessExpiresAt: Schema.String;
+        readonly lastRefreshAt: Schema.String;
+        readonly lastError: Schema.NullOr<Schema.String>;
+        readonly createdAt: Schema.String;
+        readonly updatedAt: Schema.String;
+    }>]>>;
+}>, readonly never[], true, typeof CurrentPrincipal>, Action.Action<"putCredential", Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["gh", "claude", "token"]>;
+    /** Surrounding whitespace, such as a pasted line ending, is not part of a secret: a value carrying any is refused, never altered. */
+    readonly value: Schema.Trimmed;
+    readonly host: Schema.optionalKey<Schema.String>;
+    /** Any date string JavaScript parses; a typo is refused, so alerting never loses it. Left out, it does not expire. */
+    readonly expiresAt: Schema.optionalKey<Schema.DateFromString>;
+}>, Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["gh", "claude", "token"]>;
+    /** The host a `gh` token is for; null for every other kind. */
+    readonly host: Schema.NullOr<Schema.String>;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+}>, readonly (typeof Conflict)[], false, typeof CurrentPrincipal>, Action.Action<"removeCredential", Schema.Struct<{
+    readonly name: Schema.String;
+}>, Schema.Void, readonly (typeof NotFound | typeof Conflict)[], false, typeof CurrentPrincipal>, Action.Action<"startSignIn", Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["chatgpt", "grok", "cursor"]>;
+}>, Schema.Struct<{
+    readonly signInId: Schema.String;
+    readonly credential: Schema.String;
+    readonly kind: Schema.Literals<readonly ["chatgpt", "grok", "cursor"]>;
+    readonly status: Schema.Literals<readonly ["pending", "complete", "failed", "expired"]>;
+    readonly userCode: Schema.NullOr<Schema.String>;
+    readonly verificationUrl: Schema.String;
+    readonly expiresAt: Schema.String;
+    readonly message: Schema.optionalKey<Schema.String>;
+}>, readonly (typeof Conflict | typeof UpstreamUnavailable)[], false, typeof CurrentPrincipal>, Action.Action<"getSignIn", Schema.Struct<{
+    readonly signInId: Schema.String;
+}>, Schema.Struct<{
+    readonly signInId: Schema.String;
+    readonly credential: Schema.String;
+    readonly kind: Schema.Literals<readonly ["chatgpt", "grok", "cursor"]>;
+    readonly status: Schema.Literals<readonly ["pending", "complete", "failed", "expired"]>;
+    readonly userCode: Schema.NullOr<Schema.String>;
+    readonly verificationUrl: Schema.String;
+    readonly expiresAt: Schema.String;
+    readonly message: Schema.optionalKey<Schema.String>;
+}>, readonly (typeof NotFound)[], true, typeof CurrentPrincipal>, Action.Action<"refreshCredential", Schema.Struct<{
+    readonly name: Schema.String;
+}>, Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["chatgpt", "grok", "cursor"]>;
+    readonly needsSignIn: Schema.Boolean;
+    readonly email: Schema.NullOr<Schema.String>;
+    /** The ChatGPT account a ChatGPT login is for; null for every other kind. */
+    readonly accountId: Schema.NullOr<Schema.String>;
+    readonly accessExpiresAt: Schema.String;
+    readonly lastRefreshAt: Schema.String;
+    readonly lastError: Schema.NullOr<Schema.String>;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+}>, readonly (typeof NotFound | typeof Conflict | typeof NeedsSignIn | typeof UpstreamUnavailable)[], false, typeof CurrentPrincipal>, Action.Action<"startClaudeSignIn", Schema.Struct<{
+    readonly name: Schema.String;
+}>, Schema.Struct<{
+    readonly signInId: Schema.String;
+    readonly credential: Schema.String;
+    readonly authorizeUrl: Schema.String;
+    readonly expiresAt: Schema.String;
+}>, readonly (typeof Conflict)[], false, typeof CurrentPrincipal>, Action.Action<"completeClaudeSignIn", Schema.Struct<{
+    readonly signInId: Schema.String;
+    /** As the callback page shows it: `<code>#<state>`. */
+    readonly code: Schema.String;
+}>, Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["gh", "claude", "token"]>;
+    /** The host a `gh` token is for; null for every other kind. */
+    readonly host: Schema.NullOr<Schema.String>;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+}>, readonly (typeof NotFound | typeof Conflict | typeof UpstreamUnavailable | typeof SignInRefused)[], false, typeof CurrentPrincipal>, Action.Action<"listKeys", Schema.$Record<Schema.String, Schema.Never>, Schema.Struct<{
+    readonly keys: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly credentials: Schema.$Array<Schema.String>;
+    }>>;
+}>, readonly never[], true, typeof CurrentPrincipal>, Action.Action<"putKey", Schema.Struct<{
+    readonly id: Schema.String;
+    readonly credentials: Schema.$Array<Schema.String>;
+}>, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly credentials: Schema.$Array<Schema.String>;
+}>, readonly (typeof NotFound)[], false, typeof CurrentPrincipal>, Action.Action<"listAudit", Schema.Struct<{
+    readonly limit: Schema.optionalKey<Schema.Int>;
+    readonly before: Schema.optionalKey<Schema.Int>;
+    readonly action: Schema.optionalKey<Schema.String>;
+    readonly credential: Schema.optionalKey<Schema.String>;
+    readonly keyId: Schema.optionalKey<Schema.String>;
+    readonly clientId: Schema.optionalKey<Schema.String>;
+}>, Schema.Struct<{
+    readonly entries: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.Int;
+        readonly at: Schema.String;
+        readonly actorKind: Schema.Literals<readonly ["machine", "admin", "system"]>;
+        readonly keyId: Schema.NullOr<Schema.String>;
+        readonly clientId: Schema.NullOr<Schema.String>;
+        readonly action: Schema.String;
+        readonly credential: Schema.NullOr<Schema.String>;
+        readonly remoteAddr: Schema.NullOr<Schema.String>;
+        readonly detail: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>>;
+}>, readonly never[], true, typeof CurrentPrincipal>];
+/**
+ * An operator's bearer token on the private port: an access token or API key of the admin
+ * resource, verified by its own provider.
+ */
+export declare const AdminLogin: Authentication.Descriptor<CurrentPrincipal, import("@gjermundgaraba/clankerauth-sdk/session").Caller, import("effect/http-api/HttpApiSecurity").Http, "clankercreds.admin", readonly [typeof ProviderUnavailable]>;
+export declare const AdminHttp: ActionHttp.Binding<readonly [Action.Action<"listCredentials", Schema.$Record<Schema.String, Schema.Never>, Schema.Struct<{
+    readonly credentials: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly name: Schema.String;
+        readonly kind: Schema.Literals<readonly ["gh", "claude", "token"]>;
+        /** The host a `gh` token is for; null for every other kind. */
+        readonly host: Schema.NullOr<Schema.String>;
+        readonly expiresAt: Schema.NullOr<Schema.String>;
+        readonly createdAt: Schema.String;
+        readonly updatedAt: Schema.String;
+    }>, Schema.Struct<{
+        readonly name: Schema.String;
+        readonly kind: Schema.Literals<readonly ["chatgpt", "grok", "cursor"]>;
+        readonly needsSignIn: Schema.Boolean;
+        readonly email: Schema.NullOr<Schema.String>;
+        /** The ChatGPT account a ChatGPT login is for; null for every other kind. */
+        readonly accountId: Schema.NullOr<Schema.String>;
+        readonly accessExpiresAt: Schema.String;
+        readonly lastRefreshAt: Schema.String;
+        readonly lastError: Schema.NullOr<Schema.String>;
+        readonly createdAt: Schema.String;
+        readonly updatedAt: Schema.String;
+    }>]>>;
+}>, readonly never[], true, typeof CurrentPrincipal>, Action.Action<"putCredential", Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["gh", "claude", "token"]>;
+    /** Surrounding whitespace, such as a pasted line ending, is not part of a secret: a value carrying any is refused, never altered. */
+    readonly value: Schema.Trimmed;
+    readonly host: Schema.optionalKey<Schema.String>;
+    /** Any date string JavaScript parses; a typo is refused, so alerting never loses it. Left out, it does not expire. */
+    readonly expiresAt: Schema.optionalKey<Schema.DateFromString>;
+}>, Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["gh", "claude", "token"]>;
+    /** The host a `gh` token is for; null for every other kind. */
+    readonly host: Schema.NullOr<Schema.String>;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+}>, readonly (typeof Conflict)[], false, typeof CurrentPrincipal>, Action.Action<"removeCredential", Schema.Struct<{
+    readonly name: Schema.String;
+}>, Schema.Void, readonly (typeof NotFound | typeof Conflict)[], false, typeof CurrentPrincipal>, Action.Action<"startSignIn", Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["chatgpt", "grok", "cursor"]>;
+}>, Schema.Struct<{
+    readonly signInId: Schema.String;
+    readonly credential: Schema.String;
+    readonly kind: Schema.Literals<readonly ["chatgpt", "grok", "cursor"]>;
+    readonly status: Schema.Literals<readonly ["pending", "complete", "failed", "expired"]>;
+    readonly userCode: Schema.NullOr<Schema.String>;
+    readonly verificationUrl: Schema.String;
+    readonly expiresAt: Schema.String;
+    readonly message: Schema.optionalKey<Schema.String>;
+}>, readonly (typeof Conflict | typeof UpstreamUnavailable)[], false, typeof CurrentPrincipal>, Action.Action<"getSignIn", Schema.Struct<{
+    readonly signInId: Schema.String;
+}>, Schema.Struct<{
+    readonly signInId: Schema.String;
+    readonly credential: Schema.String;
+    readonly kind: Schema.Literals<readonly ["chatgpt", "grok", "cursor"]>;
+    readonly status: Schema.Literals<readonly ["pending", "complete", "failed", "expired"]>;
+    readonly userCode: Schema.NullOr<Schema.String>;
+    readonly verificationUrl: Schema.String;
+    readonly expiresAt: Schema.String;
+    readonly message: Schema.optionalKey<Schema.String>;
+}>, readonly (typeof NotFound)[], true, typeof CurrentPrincipal>, Action.Action<"refreshCredential", Schema.Struct<{
+    readonly name: Schema.String;
+}>, Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["chatgpt", "grok", "cursor"]>;
+    readonly needsSignIn: Schema.Boolean;
+    readonly email: Schema.NullOr<Schema.String>;
+    /** The ChatGPT account a ChatGPT login is for; null for every other kind. */
+    readonly accountId: Schema.NullOr<Schema.String>;
+    readonly accessExpiresAt: Schema.String;
+    readonly lastRefreshAt: Schema.String;
+    readonly lastError: Schema.NullOr<Schema.String>;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+}>, readonly (typeof NotFound | typeof Conflict | typeof NeedsSignIn | typeof UpstreamUnavailable)[], false, typeof CurrentPrincipal>, Action.Action<"startClaudeSignIn", Schema.Struct<{
+    readonly name: Schema.String;
+}>, Schema.Struct<{
+    readonly signInId: Schema.String;
+    readonly credential: Schema.String;
+    readonly authorizeUrl: Schema.String;
+    readonly expiresAt: Schema.String;
+}>, readonly (typeof Conflict)[], false, typeof CurrentPrincipal>, Action.Action<"completeClaudeSignIn", Schema.Struct<{
+    readonly signInId: Schema.String;
+    /** As the callback page shows it: `<code>#<state>`. */
+    readonly code: Schema.String;
+}>, Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["gh", "claude", "token"]>;
+    /** The host a `gh` token is for; null for every other kind. */
+    readonly host: Schema.NullOr<Schema.String>;
+    readonly expiresAt: Schema.NullOr<Schema.String>;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+}>, readonly (typeof NotFound | typeof Conflict | typeof UpstreamUnavailable | typeof SignInRefused)[], false, typeof CurrentPrincipal>, Action.Action<"listKeys", Schema.$Record<Schema.String, Schema.Never>, Schema.Struct<{
+    readonly keys: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly credentials: Schema.$Array<Schema.String>;
+    }>>;
+}>, readonly never[], true, typeof CurrentPrincipal>, Action.Action<"putKey", Schema.Struct<{
+    readonly id: Schema.String;
+    readonly credentials: Schema.$Array<Schema.String>;
+}>, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly credentials: Schema.$Array<Schema.String>;
+}>, readonly (typeof NotFound)[], false, typeof CurrentPrincipal>, Action.Action<"listAudit", Schema.Struct<{
+    readonly limit: Schema.optionalKey<Schema.Int>;
+    readonly before: Schema.optionalKey<Schema.Int>;
+    readonly action: Schema.optionalKey<Schema.String>;
+    readonly credential: Schema.optionalKey<Schema.String>;
+    readonly keyId: Schema.optionalKey<Schema.String>;
+    readonly clientId: Schema.optionalKey<Schema.String>;
+}>, Schema.Struct<{
+    readonly entries: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.Int;
+        readonly at: Schema.String;
+        readonly actorKind: Schema.Literals<readonly ["machine", "admin", "system"]>;
+        readonly keyId: Schema.NullOr<Schema.String>;
+        readonly clientId: Schema.NullOr<Schema.String>;
+        readonly action: Schema.String;
+        readonly credential: Schema.NullOr<Schema.String>;
+        readonly remoteAddr: Schema.NullOr<Schema.String>;
+        readonly detail: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>>;
+}>, readonly never[], true, typeof CurrentPrincipal>], [], Authentication.Descriptor<CurrentPrincipal, import("@gjermundgaraba/clankerauth-sdk/session").Caller, import("effect/http-api/HttpApiSecurity").Http, "clankercreds.admin", readonly [typeof ProviderUnavailable]>>;
+export { Conflict, CredentialKind, LoginKind, Name, NeedsSignIn, NotFound, scopes, SecretKind, UpstreamUnavailable, };

package/dist/admin.js

@@ -0,0 +1,214 @@
+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 { apiPath, Conflict, CredentialKind, Host, LoginKind, Name, NeedsSignIn, NotFound, scopes, SecretKind, UpstreamUnavailable, } from "./shared.js";
+/** Written by the service, always ISO. What an operator enters is decoded as a date instead. */
+const Timestamp = Schema.String;
+/** A stored secret's state. The value itself is never read back out. */
+export const SecretStatus = Schema.Struct({
+    name: Name,
+    kind: SecretKind,
+    /** The host a `gh` token is for; null for every other kind. */
+    host: Schema.NullOr(Schema.String),
+    expiresAt: Schema.NullOr(Timestamp),
+    createdAt: Timestamp,
+    updatedAt: Timestamp,
+});
+/** A login's state. It exists from the first completed sign-in on. */
+export const LoginStatus = Schema.Struct({
+    name: Name,
+    kind: LoginKind,
+    needsSignIn: Schema.Boolean,
+    email: Schema.NullOr(Schema.String),
+    /** The ChatGPT account a ChatGPT login is for; null for every other kind. */
+    accountId: Schema.NullOr(Schema.String),
+    accessExpiresAt: Timestamp,
+    lastRefreshAt: Timestamp,
+    lastError: Schema.NullOr(Schema.String),
+    createdAt: Timestamp,
+    updatedAt: Timestamp,
+});
+export const CredentialStatus = Schema.Union([SecretStatus, LoginStatus]);
+/** The clankerauth id of a machine key. */
+const KeyId = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
+/**
+ * A machine key and the credentials it may read. A machine names which of them it syncs; a
+ * replacement key is granted the same ones and overlaps the old key until that is removed.
+ * A key may be granted several credentials of one kind: several accounts of a provider.
+ */
+export const KeyInfo = Schema.Struct({
+    id: KeyId,
+    credentials: Schema.Array(Name),
+});
+/**
+ * A pending Claude sign-in: approve at `authorizeUrl`, then hand the code the callback page
+ * shows to `completeClaudeSignIn`. The code is useless without the verifier the service holds.
+ */
+export const ClaudeSignIn = Schema.Struct({
+    signInId: Schema.String,
+    credential: Name,
+    authorizeUrl: Schema.String,
+    expiresAt: Timestamp,
+});
+/**
+ * A Claude sign-in's code was not taken: it is not this sign-in's, or Anthropic refused it.
+ * The sign-in stays open until it expires, for the code again or a new one from its
+ * `authorizeUrl`. An approval that left out a scope the token needs ends it: start again.
+ */
+export class SignInRefused extends Schema.TaggedError()("SignInRefused", { message: Schema.String }, { httpApiStatus: 422 }) {
+}
+/**
+ * A login's sign-in: open `verificationUrl` and approve, entering `userCode` where the
+ * provider asks for one. Cursor's link carries everything and has no code.
+ */
+export const SignInState = Schema.Struct({
+    signInId: Schema.String,
+    credential: Name,
+    kind: LoginKind,
+    status: Schema.Literals(["pending", "complete", "failed", "expired"]),
+    userCode: Schema.NullOr(Schema.String),
+    verificationUrl: Schema.String,
+    expiresAt: Timestamp,
+    message: Schema.optionalKey(Schema.String),
+});
+/** Credentials by name: rows outlive what they name, and stay findable. */
+export const AuditEntry = Schema.Struct({
+    id: Schema.Int,
+    at: Timestamp,
+    actorKind: Schema.Literals(["machine", "admin", "system"]),
+    keyId: Schema.NullOr(Schema.String),
+    clientId: Schema.NullOr(Schema.String),
+    action: Schema.String,
+    credential: Schema.NullOr(Schema.String),
+    remoteAddr: Schema.NullOr(Schema.String),
+    detail: Schema.Record(Schema.String, Schema.Json),
+});
+/** Every filter is optional; the page size defaults on the service. */
+export const AuditQuery = Schema.Struct({
+    limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 500 }))),
+    before: Schema.optionalKey(Schema.Int),
+    action: Schema.optionalKey(Schema.String),
+    credential: Schema.optionalKey(Name),
+    keyId: Schema.optionalKey(Schema.String),
+    clientId: Schema.optionalKey(Schema.String),
+});
+/**
+ * A read whose code or link signs an account in: exported so the server's authorization
+ * rule can name it.
+ */
+export const GetSignIn = Action.make("getSignIn", {
+    readOnly: true,
+    caller: CurrentPrincipal,
+    description: "Read a sign-in. The service holds one in memory only, until the next sign-in starts after it expired; one it no longer holds is not found.",
+    input: Schema.Struct({ signInId: Schema.String }),
+    success: SignInState,
+    error: NotFound,
+});
+/** Everything an operator does; which scope each needs is the server's authorization rule. */
+export const Admin = [
+    Action.make("listCredentials", {
+        readOnly: true,
+        caller: CurrentPrincipal,
+        description: "Every credential with its state: expiry, last refresh, last error and whether a login needs a new sign-in. Values are never returned.",
+        success: Schema.Struct({ credentials: Schema.Array(CredentialStatus) }),
+    }),
+    Action.make("putCredential", {
+        readOnly: false,
+        caller: CurrentPrincipal,
+        description: "Store a secret under a name, or replace its value and expiry: a `gh` or `claude` token a machine places, or a `token`, any other service's API key, which a service such as clankerusage reads. A `gh` token is for `host`, github.com unless given. A credential's kind and host never change; remove it and put it again instead. Keys granted it receive it on their next sync.",
+        input: Schema.Struct({
+            name: Name,
+            kind: SecretKind,
+            /** Surrounding whitespace, such as a pasted line ending, is not part of a secret: a value carrying any is refused, never altered. */
+            value: Schema.Trimmed.check(Schema.isMinLength(1), Schema.isMaxLength(16_384)),
+            host: Schema.optionalKey(Host),
+            /** Any date string JavaScript parses; a typo is refused, so alerting never loses it. Left out, it does not expire. */
+            expiresAt: Schema.optionalKey(Schema.DateFromString),
+        }).check(Schema.makeFilter(({ kind, host }) => kind === "gh" || host === undefined
+            ? undefined
+            : { path: ["host"], issue: "Only a gh credential has a host." })),
+        success: SecretStatus,
+        error: Conflict,
+    }),
+    Action.make("removeCredential", {
+        readOnly: false,
+        caller: CurrentPrincipal,
+        description: "Delete a credential. Refused while a key is still granted it.",
+        input: Schema.Struct({ name: Name }),
+        success: Schema.Void,
+        error: [NotFound, Conflict],
+    }),
+    Action.make("startSignIn", {
+        readOnly: false,
+        caller: CurrentPrincipal,
+        description: "Start a sign-in for a ChatGPT, Grok or Cursor login; the credential is created, or its login replaced, when the sign-in completes. Open the returned verificationUrl and approve, entering userCode where one is given, then poll getSignIn.",
+        input: Schema.Struct({ name: Name, kind: LoginKind }),
+        success: SignInState,
+        error: [Conflict, UpstreamUnavailable],
+    }),
+    GetSignIn,
+    Action.make("refreshCredential", {
+        readOnly: false,
+        caller: CurrentPrincipal,
+        description: "Refresh one login now instead of waiting for its schedule.",
+        input: Schema.Struct({ name: Name }),
+        success: LoginStatus,
+        error: [NotFound, Conflict, NeedsSignIn, UpstreamUnavailable],
+    }),
+    Action.make("startClaudeSignIn", {
+        readOnly: false,
+        caller: CurrentPrincipal,
+        description: "Start a sign-in for a Claude credential: a token for both Claude Code and the usage endpoint, valid for a year. Approve at the returned authorizeUrl, then pass the code the callback page shows to completeClaudeSignIn within 15 minutes.",
+        input: Schema.Struct({ name: Name }),
+        success: ClaudeSignIn,
+        error: Conflict,
+    }),
+    Action.make("completeClaudeSignIn", {
+        readOnly: false,
+        caller: CurrentPrincipal,
+        description: "Exchange the code from an approved Claude sign-in for its token, stored under the sign-in's name: created, or its value and expiry replaced. Machines receive it on their next sync.",
+        input: Schema.Struct({
+            signInId: Schema.String,
+            /** As the callback page shows it: `<code>#<state>`. */
+            code: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(4096)),
+        }),
+        success: SecretStatus,
+        error: [NotFound, Conflict, SignInRefused, UpstreamUnavailable],
+    }),
+    Action.make("listKeys", {
+        readOnly: true,
+        caller: CurrentPrincipal,
+        description: "Every machine key with the credentials it is granted.",
+        success: Schema.Struct({ keys: Schema.Array(KeyInfo) }),
+    }),
+    Action.make("putKey", {
+        readOnly: false,
+        caller: CurrentPrincipal,
+        description: "Grant a machine key, by its clankerauth id, exactly these credentials, replacing what it had; none takes every grant. A machine syncs the ones its configuration names; several of one kind may be granted. Revoke the key itself in clankerauth.",
+        input: Schema.Struct({ id: KeyId, credentials: Schema.Array(Name) }),
+        success: KeyInfo,
+        error: NotFound,
+    }),
+    Action.make("listAudit", {
+        readOnly: true,
+        caller: CurrentPrincipal,
+        description: "The audit log, newest first. Filter by action, credential, key or client id; page with `before`.",
+        input: AuditQuery,
+        success: Schema.Struct({ entries: Schema.Array(AuditEntry) }),
+    }),
+];
+/**
+ * An operator's bearer token on the private port: an access token or API key of the admin
+ * resource, verified by its own provider.
+ */
+export const AdminLogin = Authentication.make("clankercreds.admin", CurrentPrincipal, {
+    error: ProviderUnavailable,
+});
+export const AdminHttp = ActionHttp.make(Admin, {
+    prefix: apiPath,
+    authentication: AdminLogin,
+});
+export { Conflict, CredentialKind, LoginKind, Name, NeedsSignIn, NotFound, scopes, SecretKind, UpstreamUnavailable, };