@plandesk/api 0.19.0 → 1.0.0-beta.1

package/dist/auth.js

@@ -1,6 +1,23 @@
 import { timingSafeEqual } from 'node:crypto';
+import { DEFAULT_ORG_ID, hashShareToken, orgRoles, verifyGuestSession, } from '@plandesk/db';
+import { applyAgentKeyPermissionCeiling, verifyBetterAuthApiKey, } from './agent-keys.js';
+import { runWithAuthContext, tryGetAuthContext } from './auth-context.js';
+import { userRefFromGithubAccountId } from './identity.js';
+import { resolveDefaultOrganization } from './organizations.js';
+import { hasAnyWritePermission, orgRoleToPermissionSet, } from './permissions.js';
+import { readGuestSessionCookie } from './session.js';
 const BASIC_PREFIX = 'Basic ';
 const BASIC_USER = 'plandesk';
+const BEARER_PREFIX = 'Bearer ';
+const GITHUB_PROVIDER_ID = 'github';
+function parseOrgRole(role) {
+    for (const candidate of orgRoles) {
+        if (candidate === role) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
 function decodeBasicAuth(header) {
     if (!header.startsWith(BASIC_PREFIX)) {
         return undefined;
@@ -18,6 +35,308 @@ function credentialsMatch(provided, expected) {
     }
     return timingSafeEqual(provided, expected);
 }
+function extractBearerToken(header) {
+    if (header === undefined || !header.toLowerCase().startsWith(BEARER_PREFIX.toLowerCase())) {
+        return undefined;
+    }
+    const raw = header.slice(BEARER_PREFIX.length).trim();
+    return raw.length > 0 ? raw : undefined;
+}
+/** True when the server is bound only to loopback (trusted local network boundary). */
+export function isLoopbackBind(host) {
+    const h = host.trim().toLowerCase();
+    return h === '127.0.0.1' || h === '::1' || h === 'localhost';
+}
+/**
+ * Resolve a better-auth session into AuthContext.
+ * - null session → undefined (caller falls through to loopback)
+ * - session but no org membership → 'unauthorized' (authenticated-but-org-less)
+ * - session + membership → AuthContext kind session
+ */
+async function resolveBetterAuthSessionContext(auth, headers) {
+    const session = await auth.api.getSession({ headers });
+    if (session === null) {
+        return undefined;
+    }
+    const adapter = (await auth.$context).adapter;
+    const userId = session.user.id;
+    const members = await adapter.findMany({
+        model: 'member',
+        where: [{ field: 'userId', value: userId }],
+        sortBy: { field: 'createdAt', direction: 'asc' },
+    });
+    // Membership revoked or never granted: cookie carries no org authority.
+    if (members.length === 0) {
+        return 'unauthorized';
+    }
+    const sessionRow = await adapter.findOne({
+        model: 'session',
+        where: [{ field: 'token', value: session.session.token }],
+    });
+    const activeOrganizationId = sessionRow?.activeOrganizationId;
+    const active = (activeOrganizationId === undefined || activeOrganizationId === null
+        ? undefined
+        : members.find((member) => member.organizationId === activeOrganizationId)) ?? members[0];
+    if (active === undefined) {
+        return 'unauthorized';
+    }
+    if (active.organizationId !== activeOrganizationId) {
+        await (await auth.$context).internalAdapter.updateSession(session.session.token, {
+            activeOrganizationId: active.organizationId,
+        });
+    }
+    const role = parseOrgRole(active.role);
+    if (role === undefined) {
+        return 'unauthorized';
+    }
+    // GitHub-linked users keep github:<id> as the stable ref (BA4a).
+    // Password-only members (invite bootstrap, no GitHub app — REQ-20 / BA3c)
+    // use user:<better-auth user id> so they can hold a session AuthContext.
+    const account = await adapter.findOne({
+        model: 'account',
+        where: [
+            { field: 'userId', value: userId },
+            { field: 'providerId', value: GITHUB_PROVIDER_ID },
+        ],
+    });
+    let userRef;
+    if (account !== null) {
+        try {
+            userRef = userRefFromGithubAccountId(account.accountId);
+        }
+        catch {
+            return 'unauthorized';
+        }
+    }
+    else {
+        userRef = `user:${userId}`;
+    }
+    return {
+        kind: 'session',
+        orgId: active.organizationId,
+        userRef,
+        role,
+        permission: orgRoleToPermissionSet(role),
+    };
+}
+/**
+ * Read better-auth key metadata. Absent/unknown `kind` → `'agent'` (BA4b-1
+ * back-compat: every key minted without kind keeps agent ceiling).
+ */
+function readApiKeyMetadata(metadata) {
+    if (metadata === null || metadata === undefined || typeof metadata !== 'object') {
+        return { orgId: undefined, projectId: undefined, kind: 'agent' };
+    }
+    const m = metadata;
+    return {
+        orgId: typeof m.orgId === 'string' && m.orgId.length > 0 ? m.orgId : undefined,
+        projectId: typeof m.projectId === 'string' && m.projectId.length > 0 ? m.projectId : undefined,
+        kind: m.kind === 'owner' ? 'owner' : 'agent',
+    };
+}
+/**
+ * Resolve live better-auth member role for (userId, orgId).
+ * No member row → undefined (ceiling becomes empty permissions).
+ */
+async function resolveBetterAuthLiveRole(auth, userId, orgId) {
+    const adapter = (await auth.$context).adapter;
+    const members = await adapter.findMany({
+        model: 'member',
+        where: [
+            { field: 'userId', value: userId },
+            { field: 'organizationId', value: orgId },
+        ],
+    });
+    const active = members[0];
+    if (active === undefined) {
+        return undefined;
+    }
+    return parseOrgRole(active.role);
+}
+/**
+ * Try better-auth API key first (BA5). Returns:
+ * - AuthContext when the bearer is a valid better-auth key with org metadata
+ * - 'unauthorized' when the key is valid but unusable (no org)
+ * - undefined when not a better-auth key (caller rejects as 401)
+ */
+async function resolveBetterAuthApiKeyContext(auth, bearer) {
+    const verified = await verifyBetterAuthApiKey(auth, bearer);
+    if (verified === undefined) {
+        return undefined;
+    }
+    const userId = verified.referenceId;
+    const { orgId, projectId, kind } = readApiKeyMetadata(verified.metadata);
+    if (orgId === undefined) {
+        return 'unauthorized';
+    }
+    const liveRole = await resolveBetterAuthLiveRole(auth, userId, orgId);
+    const permission = applyAgentKeyPermissionCeiling(verified.permissions, liveRole, kind);
+    return {
+        kind: 'apikey',
+        orgId,
+        userId,
+        ...(projectId !== undefined ? { projectId } : {}),
+        role: liveRole,
+        permission,
+    };
+}
+/**
+ * Endpoints that must answer before the caller holds a credential: the method
+ * probe the sign-in UI reads, and better-auth's own sign-in surface at /api/auth/*
+ * (chicken-and-egg: cannot require a token to obtain one).
+ */
+const PUBLIC_AUTH_PATHS = new Set([
+    '/api/v1/auth/methods',
+    '/api/auth/*',
+]);
+/** Invitation accept: invitee may have a session but zero org memberships yet. */
+const INVITATION_ACCEPT_PATH = /^\/api\/v1\/invitations\/[^/]+\/accept$/;
+export function isInvitationAcceptPath(path) {
+    return INVITATION_ACCEPT_PATH.test(path);
+}
+export function isPublicAuthPath(path) {
+    if (PUBLIC_AUTH_PATHS.has(path)) {
+        return true;
+    }
+    // better-auth mounts under /api/auth/*; the set holds the prefix pattern.
+    if (path === '/api/auth' || path.startsWith('/api/auth/')) {
+        return true;
+    }
+    // BA3c: accept is session-checked in-handler, not org-gated.
+    return isInvitationAcceptPath(path);
+}
+/**
+ * Pre-join share surfaces: meta (render "X invited you"), join (claim a guest
+ * session), and agent markdown links. The portal *view* is NOT public — it
+ * requires a guest session issued by join. Share *creation* lives under
+ * /tasks/:id/share and /documents/:id/share (org-gated).
+ */
+const PUBLIC_SHARE_PATH = /^\/api\/v1\/share\/[^/]+(\.md|\/meta|\/join)$/;
+export function isPublicShareReadPath(path) {
+    return PUBLIC_SHARE_PATH.test(path);
+}
+/**
+ * Guest-gated portal surfaces: view + submissions (list/submit).
+ * Never fall through to loopback/org auth — that would re-open the pre-join bypass.
+ */
+const SHARE_GUEST_PATH = /^\/api\/v1\/share\/([^/]+)\/(view|submissions)$/;
+export function isShareGuestViewPath(path) {
+    return SHARE_GUEST_PATH.test(path);
+}
+export function extractShareTokenFromViewPath(path) {
+    const match = SHARE_GUEST_PATH.exec(path);
+    return match?.[1];
+}
+function extractGuestCredential(authorizationHeader, cookieToken) {
+    return extractBearerToken(authorizationHeader) ?? cookieToken;
+}
+/**
+ * Always-on org resolver for every request:
+ * 1. Bearer → better-auth API key (BA5 live-role ceiling) when configured
+ * 2. else better-auth session cookie → active org + member role (when configured)
+ * 3. else loopback bind + single-org → default org as owner (local, zero friction)
+ * 4. else 401
+ *
+ * A stranger bearer that is not a better-auth key is always 401 (no mcp_token fallback).
+ * Every branch yields the same `{ orgId, permission }`, so services downstream
+ * are identical for a browser, the CLI, and an agent.
+ */
+export function createOrgAuthMiddleware(options) {
+    const { db, bindHost, betterAuth } = options;
+    return async (c, next) => {
+        if (isPublicAuthPath(c.req.path) || isPublicShareReadPath(c.req.path)) {
+            await next();
+            return;
+        }
+        // Portal view: guest session only — never loopback/org. No credential → 401
+        // closes the pre-join bypass; wrong-share session → 404 (no existence leak).
+        if (isShareGuestViewPath(c.req.path)) {
+            const shareToken = extractShareTokenFromViewPath(c.req.path);
+            if (shareToken === undefined) {
+                return c.json({ error: 'not_found' }, 404);
+            }
+            const guestRaw = extractGuestCredential(c.req.header('Authorization'), readGuestSessionCookie(c));
+            if (guestRaw === undefined) {
+                return c.json({ error: 'unauthorized' }, 401);
+            }
+            const guest = await verifyGuestSession(db, guestRaw);
+            if (guest === undefined) {
+                return c.json({ error: 'unauthorized' }, 401);
+            }
+            if (guest.share.tokenHash !== hashShareToken(shareToken)) {
+                return c.json({ error: 'not_found' }, 404);
+            }
+            const ctx = {
+                kind: 'guest',
+                shareId: guest.shareId,
+                projectId: guest.projectId,
+                guestSessionId: guest.id,
+            };
+            await runWithAuthContext(ctx, async () => {
+                await next();
+            });
+            return;
+        }
+        const bearer = extractBearerToken(c.req.header('Authorization'));
+        if (bearer !== undefined) {
+            if (betterAuth !== undefined) {
+                const apiKeyCtx = await resolveBetterAuthApiKeyContext(betterAuth, bearer);
+                if (apiKeyCtx === 'unauthorized') {
+                    return c.json({ error: 'unauthorized' }, 401);
+                }
+                if (apiKeyCtx !== undefined) {
+                    await runWithAuthContext(apiKeyCtx, async () => {
+                        await next();
+                    });
+                    return;
+                }
+            }
+            // Not a better-auth key (or better-auth not configured): no mcp_token fallback.
+            return c.json({ error: 'unauthorized' }, 401);
+        }
+        if (betterAuth !== undefined) {
+            const betterAuthCtx = await resolveBetterAuthSessionContext(betterAuth, c.req.raw.headers);
+            if (betterAuthCtx === 'unauthorized') {
+                return c.json({ error: 'unauthorized' }, 401);
+            }
+            if (betterAuthCtx !== undefined) {
+                await runWithAuthContext(betterAuthCtx, async () => {
+                    await next();
+                });
+                return;
+            }
+        }
+        if (isLoopbackBind(bindHost)) {
+            // REQ-21: local loopback is always owner — no login, no member row required.
+            // Prefer the ensured better-auth default org when present; else DEFAULT_ORG_ID.
+            // Soft-fail if BA tables are not migrated yet (createApp boots before migrator).
+            let orgId = DEFAULT_ORG_ID;
+            if (betterAuth !== undefined) {
+                try {
+                    const org = await resolveDefaultOrganization(betterAuth);
+                    if (org !== undefined) {
+                        orgId = org.id;
+                    }
+                }
+                catch {
+                    // organization table missing / adapter error — keep DEFAULT_ORG_ID
+                }
+            }
+            const ctx = {
+                kind: 'loopback',
+                orgId,
+                role: 'owner',
+                permission: orgRoleToPermissionSet('owner'),
+            };
+            await runWithAuthContext(ctx, async () => {
+                await next();
+            });
+            return;
+        }
+        return c.json({ error: 'unauthorized' }, 401);
+    };
+}
+/** Optional Basic auth gate (PLANDESK_AUTH_PASSWORD). Skips MCP paths. */
 export function createAuthMiddleware(password) {
     const expected = Buffer.from(`${BASIC_USER}:${password}`, 'utf8');
     return async (c, next) => {
@@ -25,6 +344,16 @@ export function createAuthMiddleware(password) {
             await next();
             return;
         }
+        // Method probe and better-auth sign-in must stay reachable without Basic.
+        if (isPublicAuthPath(c.req.path) || isPublicShareReadPath(c.req.path)) {
+            await next();
+            return;
+        }
+        // Bearer tokens are handled by org auth; do not require Basic on top of them.
+        if (extractBearerToken(c.req.header('Authorization')) !== undefined) {
+            await next();
+            return;
+        }
         const decoded = decodeBasicAuth(c.req.header('Authorization') ?? '');
         if (decoded === undefined || !credentialsMatch(decoded, expected)) {
             return c.json({ error: 'unauthorized' }, 401, {
@@ -34,4 +363,32 @@ export function createAuthMiddleware(password) {
         await next();
     };
 }
+/**
+ * Reject pure read-only callers (empty permission set) on write HTTP methods.
+ * Resource:action checks are enforced in services via requirePermission.
+ */
+/** Guest may POST only moderated submissions for their share (BA6b). */
+const SHARE_GUEST_SUBMIT_PATH = /^\/api\/v1\/share\/[^/]+\/submissions$/;
+export function createWriteGuardMiddleware() {
+    return async (c, next) => {
+        const method = c.req.method.toUpperCase();
+        if (method !== 'GET' && method !== 'HEAD' && method !== 'OPTIONS') {
+            const ctx = tryGetAuthContext();
+            if (ctx !== undefined) {
+                if (ctx.kind === 'guest') {
+                    // Moderated inbox only — every other write stays forbidden for guests.
+                    if (method === 'POST' && SHARE_GUEST_SUBMIT_PATH.test(c.req.path)) {
+                        await next();
+                        return;
+                    }
+                    return c.json({ error: 'forbidden' }, 403);
+                }
+                if (!hasAnyWritePermission(ctx.permission)) {
+                    return c.json({ error: 'forbidden' }, 403);
+                }
+            }
+        }
+        await next();
+    };
+}
 //# sourceMappingURL=auth.js.map

package/dist/better-auth.d.ts

@@ -0,0 +1,66 @@
+/**
+ * better-auth foundation (migration slice 1/6).
+ *
+ * Nothing in this app consumes this yet — `createApp` mounts the handler
+ * (see server.ts) but every existing route keeps going through
+ * `createOrgAuthMiddleware` exactly as before. This file only proves the
+ * config boots on our driver.
+ *
+ * Dialect choice (REQ-3): a Kysely `LibsqlDialect`, not `drizzleAdapter`.
+ * `@better-auth/cli` (which would normally generate a Drizzle schema for
+ * the adapter) is pinned two minors behind this `better-auth` release, so
+ * its output can't be trusted to match — hand-rolling a Drizzle schema for
+ * the tables we don't own the shape of is the same trust problem by hand.
+ * The Kysely dialect needs no generated schema: better-auth introspects and
+ * creates its own tables at runtime (see `runBetterAuthMigrations` below).
+ * This is exactly what `scratchpad/ba-spike/spike.mjs` proved 9/9 on.
+ *
+ * Migration seam (REQ-4): better-auth's tables are created by
+ * `better-auth/db/migration`'s runtime migrator, which diffs the live
+ * schema via Kysely's introspector and emits `CREATE TABLE` for whatever
+ * is missing — it keeps no ledger table of its own. Our 16 Drizzle
+ * migrations keep bookkeeping in `__drizzle_migrations`. Two independent,
+ * non-overlapping table sets, two independent, non-overlapping bookkeeping
+ * mechanisms: neither can fight over the other's tables or history.
+ *
+ * The dialect wraps the SAME libSQL `Client` the caller's `Db` already
+ * holds (`db.$client`), rather than opening a second connection from a
+ * URL. A fresh `:memory:` URL would open a second, empty, unrelated
+ * database — see the connection-per-transaction footgun documented next to
+ * `withTransaction` in `@plandesk/db`'s client.ts — so sharing the
+ * connection is required for correctness, not just efficiency.
+ */
+import { type Auth } from 'better-auth';
+import type { Client, Db } from '@plandesk/db';
+export type BetterAuthDeps = {
+    /** The app's existing libSQL connection — shared, never a second one. */
+    client: Client;
+    /**
+     * App Db for personal-org provisioning on first GitHub session (BA4c).
+     * When omitted, databaseHooks are not installed (foundation tests only).
+     */
+    db?: Db;
+    /** Absent secret -> feature is off, still boots (mirrors `github: undefined`). */
+    secret: string | undefined;
+    baseURL: string;
+    github?: {
+        clientId: string;
+        clientSecret: string;
+    };
+};
+/**
+ * Erase the exact plugin tuple from the public type so TypeScript can emit a
+ * stable declaration while retaining the handler, adapter context, and API.
+ * Plugin endpoints (verifyApiKey / createApiKey) are reached via runtime-
+ * validated accessors in agent-keys.ts (BA5).
+ */
+export type BetterAuthInstance = Auth;
+/** Absent secret -> undefined, the supported no-auth-mounted state (REQ-5). */
+export declare function createBetterAuth(deps: BetterAuthDeps): BetterAuthInstance | undefined;
+/**
+ * Create better-auth's tables against the shared connection. Node CLI boot
+ * and operator migration paths call this explicitly; edge request handlers do
+ * not migrate.
+ */
+export declare function runBetterAuthMigrations(auth: BetterAuthInstance): Promise<void>;
+//# sourceMappingURL=better-auth.d.ts.map

package/dist/better-auth.js

@@ -0,0 +1,106 @@
+/**
+ * better-auth foundation (migration slice 1/6).
+ *
+ * Nothing in this app consumes this yet — `createApp` mounts the handler
+ * (see server.ts) but every existing route keeps going through
+ * `createOrgAuthMiddleware` exactly as before. This file only proves the
+ * config boots on our driver.
+ *
+ * Dialect choice (REQ-3): a Kysely `LibsqlDialect`, not `drizzleAdapter`.
+ * `@better-auth/cli` (which would normally generate a Drizzle schema for
+ * the adapter) is pinned two minors behind this `better-auth` release, so
+ * its output can't be trusted to match — hand-rolling a Drizzle schema for
+ * the tables we don't own the shape of is the same trust problem by hand.
+ * The Kysely dialect needs no generated schema: better-auth introspects and
+ * creates its own tables at runtime (see `runBetterAuthMigrations` below).
+ * This is exactly what `scratchpad/ba-spike/spike.mjs` proved 9/9 on.
+ *
+ * Migration seam (REQ-4): better-auth's tables are created by
+ * `better-auth/db/migration`'s runtime migrator, which diffs the live
+ * schema via Kysely's introspector and emits `CREATE TABLE` for whatever
+ * is missing — it keeps no ledger table of its own. Our 16 Drizzle
+ * migrations keep bookkeeping in `__drizzle_migrations`. Two independent,
+ * non-overlapping table sets, two independent, non-overlapping bookkeeping
+ * mechanisms: neither can fight over the other's tables or history.
+ *
+ * The dialect wraps the SAME libSQL `Client` the caller's `Db` already
+ * holds (`db.$client`), rather than opening a second connection from a
+ * URL. A fresh `:memory:` URL would open a second, empty, unrelated
+ * database — see the connection-per-transaction footgun documented next to
+ * `withTransaction` in `@plandesk/db`'s client.ts — so sharing the
+ * connection is required for correctness, not just efficiency.
+ */
+import { betterAuth } from 'better-auth';
+import { organization } from 'better-auth/plugins';
+import { apiKey } from '@better-auth/api-key';
+import { LibsqlDialect } from '@libsql/kysely-libsql';
+import { ac, admin, member, owner } from './access-control.js';
+import { provisionPersonalOrgIfNeeded, setDefaultActiveOrganization } from './identity.js';
+/** Absent secret -> undefined, the supported no-auth-mounted state (REQ-5). */
+export function createBetterAuth(deps) {
+    if (deps.secret === undefined || deps.secret.length === 0) {
+        return undefined;
+    }
+    // Closed over after construction so session.create.after can use the instance.
+    let authInstance;
+    const appDb = deps.db;
+    const options = {
+        database: { dialect: new LibsqlDialect({ client: deps.client }), type: 'sqlite' },
+        secret: deps.secret,
+        baseURL: deps.baseURL,
+        emailAndPassword: { enabled: true, disableSignUp: true },
+        account: {
+            accountLinking: {
+                enabled: true,
+                requireLocalEmailVerified: true,
+                trustedProviders: ['github'],
+            },
+        },
+        ...(deps.github === undefined
+            ? {}
+            : {
+                socialProviders: {
+                    github: { clientId: deps.github.clientId, clientSecret: deps.github.clientSecret },
+                },
+            }),
+        // BA4c: session.create fires after OAuth has linked the github account
+        // (user+account already exist). Invited members already hold a member row
+        // so provision is a no-op. Public adapter.create (test seeds) does not fire
+        // these hooks — only internalAdapter / real OAuth paths do.
+        ...(appDb === undefined
+            ? {}
+            : {
+                databaseHooks: {
+                    session: {
+                        create: {
+                            after: async (session) => {
+                                if (authInstance === undefined)
+                                    return;
+                                await provisionPersonalOrgIfNeeded(authInstance, appDb, session.userId);
+                                await setDefaultActiveOrganization(authInstance, session.userId, session.token);
+                            },
+                        },
+                    },
+                },
+            }),
+        plugins: [
+            organization({ ac, roles: { owner, admin, member } }),
+            // enableMetadata: projectId + orgId on agent keys (BA5). Rate limit off —
+            // agent traffic is bursty; ceilings are permission-based, not request-count.
+            apiKey({ enableMetadata: true, rateLimit: { enabled: false } }),
+        ],
+    };
+    authInstance = betterAuth(options);
+    return authInstance;
+}
+/**
+ * Create better-auth's tables against the shared connection. Node CLI boot
+ * and operator migration paths call this explicitly; edge request handlers do
+ * not migrate.
+ */
+export async function runBetterAuthMigrations(auth) {
+    const { getMigrations } = await import('better-auth/db/migration');
+    const { runMigrations } = await getMigrations(auth.options);
+    await runMigrations();
+}
+//# sourceMappingURL=better-auth.js.map

package/dist/github.d.ts

@@ -0,0 +1,57 @@
+/**
+ * GitHub OAuth helpers (authorize URL + code exchange for identity).
+ * Browser sign-in is owned by better-auth social. GitHub is optional (REQ-20).
+ */
+/**
+ * The slice of fetch this module uses. Declared rather than `typeof fetch`:
+ * the ambient global signature varies by runtime (the Workers types widen it),
+ * and pinning our own keeps the injected test double honestly typed.
+ */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export type GithubConfig = {
+    clientId: string;
+    clientSecret: string;
+    /** Absolute callback URL registered with the GitHub app. */
+    callbackUrl: string;
+    /** Where to land the browser once the cookie is set. Defaults to '/'. */
+    dashboardUrl?: string;
+    /** Injectable for tests — never call the network in a test. */
+    fetch?: FetchLike;
+};
+/** Identity we keep. The access token is deliberately discarded after this. */
+export type GithubIdentity = {
+    /** GitHub's numeric account id — stable across renames. */
+    id: number;
+    login: string;
+    name: string | null;
+};
+export declare class GithubOAuthError extends Error {
+    constructor(message: string);
+}
+export type GithubEnv = {
+    PLANDESK_GITHUB_CLIENT_ID?: string;
+    PLANDESK_GITHUB_CLIENT_SECRET?: string;
+    PLANDESK_GITHUB_CALLBACK_URL?: string;
+    PLANDESK_DASHBOARD_URL?: string;
+};
+/**
+ * Read the GitHub app from the environment. Every runtime entry uses this, so
+ * "is GitHub sign-in on?" has exactly one answer everywhere.
+ *
+ * No client id/secret → undefined → the instance runs without GitHub sign-in.
+ * That is the supported self-host path, not a degraded one (REQ-20).
+ *
+ * A half-configured app throws instead of silently disabling: someone who set
+ * a client id meant to turn this on and should be told what is missing.
+ */
+export declare function githubConfigFromEnv(env: GithubEnv): GithubConfig | undefined;
+/** `github:<numeric id>` — never the login, which a rename would orphan. */
+export declare function userRefFromGithubId(id: number): string;
+export declare function authorizeUrl(config: GithubConfig, state: string): string;
+/**
+ * Exchange the callback code for the caller's identity.
+ * The access token is used once, here, and then dropped: storing it would make
+ * Plan Desk a breach target for no product benefit.
+ */
+export declare function resolveGithubIdentity(config: GithubConfig, code: string): Promise<GithubIdentity>;
+//# sourceMappingURL=github.d.ts.map