@dontcode2/backend 0.2.0 → 0.2.1

package/README.md

@@ -98,6 +98,47 @@ const client = dontcode({ baseUrl: mock.url, apiKey: 'dc_test' })
 await mock.close()
 ```
 
+## MCP server (Claude Code and other AI tools)
+
+This package ships an MCP server so an AI agent can work on a DontCode project
+directly: sign in from the terminal, query and update the database, run
+migrations, and manage files. It runs over stdio, so the tool launches it for
+you.
+
+```jsonc
+// .mcp.json (Claude Code)
+{
+  "mcpServers": {
+    "dontcode": {
+      "command": "npx",
+      "args": ["-y", "-p", "@dontcode2/backend", "dontcode", "mcp"]
+    }
+  }
+}
+```
+
+On first use the agent calls the `auth_login` tool, which opens your browser.
+You confirm a short code, pick a project, and approve; the browser hands a
+short-lived, project-scoped token back to the terminal (cached under
+`~/.dontcode`). The token is bound to your user, and the gateway enforces your
+project role on every request, so the agent can never do more than you can.
+
+CLI equivalents:
+
+```bash
+npx -p @dontcode2/backend dontcode login    # browser sign-in
+npx -p @dontcode2/backend dontcode status   # project + role + capabilities
+npx -p @dontcode2/backend dontcode logout   # forget the cached token
+```
+
+For non-interactive use (CI), set `DONTCODE_API_KEY` to a `dc_` project key and
+skip `login`. Set `DONTCODE_API_URL` to target a non-default gateway.
+
+Tools: `auth_login`, `auth_wait`, `auth_status`, `auth_logout`, `db_query`,
+`db_insert`, `db_update`, `db_delete`, `db_migrate`, `storage_list`,
+`storage_get_url`, `storage_temporary_url`, `storage_upload`, `storage_remove`,
+`storage_move`. Writes and deletes are annotated so the agent confirms first.
+
 ## Auth
 
 The API key (`Authorization: Bearer dc_…`) identifies your **project** and is sent on

package/dist/auth-device.d.ts

@@ -0,0 +1,43 @@
+import { type StoredCredential } from './credentials';
+export interface DeviceStartResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    interval: number;
+    expires_in: number;
+}
+export interface DeviceTokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    project_id: string;
+}
+export declare function startDeviceAuth(baseUrl: string, clientName?: string): Promise<DeviceStartResponse>;
+export interface PollOptions {
+    onPending?: () => void;
+    /** Stop polling after this many ms (throws code `WaitTimeout`), so a caller
+     *  like an MCP tool can poll in bounded slices instead of blocking for the
+     *  full 10-minute window. Defaults to the request's own expiry. */
+    maxWaitMs?: number;
+}
+/**
+ * Poll until the request is approved (token), denied/expired (throws), or the
+ * wait budget closes (throws 408). Honors the server's interval and `slow_down`.
+ */
+export declare function pollDeviceToken(baseUrl: string, start: DeviceStartResponse, opts?: PollOptions): Promise<DeviceTokenResponse>;
+/** Best-effort: open the verification URL in the user's browser. */
+export declare function openBrowser(url: string): Promise<void>;
+export interface LoginOptions {
+    baseUrl: string;
+    clientName?: string;
+    /** Open the browser automatically. Default true. */
+    open?: boolean;
+    /** Where human-facing prompts go. Default: no-op. */
+    log?: (message: string) => void;
+}
+/**
+ * Run the full device flow and cache the resulting credential. Returns the
+ * stored credential (token, project, expiry).
+ */
+export declare function login(options: LoginOptions): Promise<StoredCredential>;

package/dist/auth.d.ts

@@ -0,0 +1,102 @@
+import { Transport } from './http';
+import { type DecodedSession, type GetSessionInput, type SessionOptions, type SessionResult } from './session';
+import type { ForgotPasswordInput, LoginInput, LoginResult, MeResult, MfaChallengeInput, MfaDisableInput, MfaEnrollConfirmInput, MfaEnrollResult, ResetPasswordInput, SignupInput, SignupResult, SimpleResult, VerifyEmailInput } from './types';
+/** Shape of `GET /api/v1/info`: validates the credential and reports what it
+ *  can do. For device tokens, capabilities follow the signed-in user's role. */
+export interface InfoResult {
+    project: {
+        id: string;
+        name: string | null;
+    };
+    credential: {
+        type: 'api_key' | 'device';
+        role: string | null;
+        user_id: string | null;
+    };
+    capabilities: Record<string, boolean>;
+}
+/**
+ * MFA is per-user and opt-in. `enroll`/`enrollConfirm`/`disable` act as the
+ * signed-in user, so they need the end-user access token. `challenge` does
+ * not; it completes a login that returned `mfa_required`, exchanging the
+ * short-lived challenge token for real session tokens.
+ */
+export declare class MfaApi {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Complete an MFA login. Pass the `challenge_token` from `login`, plus
+     *  either the authenticator `code` or a `recoveryCode`. */
+    challenge(input: MfaChallengeInput): Promise<LoginResult>;
+    /** Begin enrollment. Render the returned `otpauth_url` as a QR code.
+     *  Enrollment stays pending until `enrollConfirm`. */
+    enroll(input: {
+        accessToken: string;
+    }): Promise<MfaEnrollResult>;
+    /** Confirm enrollment with the first authenticator code. The returned
+     *  `recovery_codes` are shown once and never again. */
+    enrollConfirm(input: MfaEnrollConfirmInput): Promise<SimpleResult>;
+    /** Turn MFA off. Proves possession of the second factor via `code` or
+     *  `recoveryCode`. */
+    disable(input: MfaDisableInput): Promise<SimpleResult>;
+}
+/**
+ * Fronts DontCode Auth with the same shapes as the gateway. Two behaviours are
+ * project settings (not API flags) and your code must handle both states:
+ * email verification (signup may not return tokens) and MFA (login may be two
+ * steps). Branch on the resolved value; never assume one round-trip.
+ */
+export declare class AuthApi {
+    private readonly transport;
+    readonly mfa: MfaApi;
+    private readonly sessions;
+    constructor(transport: Transport, sessionOptions?: SessionOptions);
+    /** Create an account. If the project requires email verification the
+     *  response has `verification_required: true` and NO tokens; collect a
+     *  code and call `verifyEmail`, then `login`. */
+    signup(input: SignupInput): Promise<SignupResult>;
+    /** Authenticate. Branch on `mfa_required`: when true you hold only a
+     *  challenge (finish via `mfa.challenge`); otherwise `tokens` is your
+     *  session. A 403 `EmailNotVerified` means the email step isn't done. */
+    login(input: LoginInput): Promise<LoginResult>;
+    /** Validate the current credential (API key or device token) and report the
+     *  project, the caller's role, and which capabilities that role grants.
+     *  Backs the MCP "is my session still good" check. */
+    info(): Promise<InfoResult>;
+    /** Resolve the signed-in user from their access token, or `{ user: null }`.
+     *  This is a network round-trip; for a per-navigation guard prefer
+     *  `getSession`, which can answer offline and caches verified results. */
+    me(input: {
+        accessToken: string;
+        timeoutMs?: number;
+    }): Promise<MeResult>;
+    /**
+     * Resolve an access token into a session for a route guard, the one call
+     * that replaces "hit `me` on every navigation". Two modes:
+     *
+     *   - `'optimistic'` (default): decode the token locally and trust its
+     *     claims. Zero network, zero stall. The right default for gating page
+     *     loads. It does NOT verify the signature and will not notice a
+     *     server-side revocation until the token's own `exp`.
+     *   - `'verified'`: confirm against the gateway's `me`, cached for a short
+     *     TTL with a hard timeout. Use it before sensitive actions. On a
+     *     timeout/outage it returns `status: 'unavailable'` with the optimistic
+     *     user, so you choose whether to fail open rather than the SDK guessing.
+     *
+     * See the BYOC docs ("Sessions") for the full reasoning and best practices.
+     */
+    getSession(input: GetSessionInput): Promise<SessionResult>;
+    /** Read the access token from a `Cookie` request header and resolve it, in
+     *  one call. `name` defaults to `dc_access_token`. Returns the anonymous
+     *  session when no cookie is present. */
+    sessionFromCookies(cookieHeader: string | null | undefined, options?: {
+        mode?: GetSessionInput['mode'];
+        cookieName?: string;
+    }): Promise<SessionResult>;
+    /** Decode an access token's claims locally without a network call or any
+     *  signature check. Convenience re-export of `decodeAccessToken`. */
+    decodeToken(token: string): DecodedSession | null;
+    /** Confirm the 6-digit code emailed at signup. */
+    verifyEmail(input: VerifyEmailInput): Promise<SimpleResult>;
+    forgotPassword(input: ForgotPasswordInput): Promise<SimpleResult>;
+    resetPassword(input: ResetPasswordInput): Promise<SimpleResult>;
+}