@plandesk/api 0.20.0 → 1.0.0-beta.2

package/dist/invitations.js

@@ -0,0 +1,211 @@
+/**
+ * better-auth organization invitations (BA3c).
+ *
+ * createInvitation / acceptInvitation / removeMember require session headers
+ * (orgSessionMiddleware). Plugin methods are not on the erased Auth type —
+ * call via runtime-validated Reflect, same pattern as agent-keys.ts.
+ */
+import { makeSignature } from 'better-auth/crypto';
+export const INVITATION_ROLES = ['owner', 'admin', 'member'];
+export function isInvitationRole(value) {
+    return INVITATION_ROLES.includes(value);
+}
+export function invitationClaimUrl(baseURL, invitationId) {
+    const base = baseURL.replace(/\/$/, '');
+    return `${base}/invite/${invitationId}`;
+}
+const SHELL_EMAIL = 'shell@plandesk.local';
+const SHELL_NAME = 'Plan Desk shell';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function isAuthApiError(err) {
+    if (!isRecord(err))
+        return false;
+    return (typeof err.statusCode === 'number' &&
+        typeof err.status === 'string' &&
+        typeof err.message === 'string');
+}
+async function callPluginApi(auth, method, args) {
+    const api = auth.api;
+    if (!(method in api)) {
+        throw new Error(`better-auth ${method} is not available`);
+    }
+    const fn = Reflect.get(api, method);
+    if (typeof fn !== 'function') {
+        throw new Error(`better-auth ${method} is not a function`);
+    }
+    return fn.call(api, args);
+}
+function parseInvitation(raw) {
+    if (!isRecord(raw) || typeof raw.id !== 'string') {
+        throw new Error('createInvitation did not return an invitation id');
+    }
+    return {
+        id: raw.id,
+        email: typeof raw.email === 'string' ? raw.email : '',
+        role: typeof raw.role === 'string' ? raw.role : '',
+        organizationId: typeof raw.organizationId === 'string' ? raw.organizationId : '',
+        inviterId: typeof raw.inviterId === 'string' ? raw.inviterId : '',
+        status: typeof raw.status === 'string' ? raw.status : '',
+        expiresAt: raw.expiresAt instanceof Date ? raw.expiresAt : new Date(String(raw.expiresAt ?? '')),
+        createdAt: raw.createdAt instanceof Date ? raw.createdAt : new Date(String(raw.createdAt ?? '')),
+    };
+}
+/**
+ * Create an invitation using the caller's better-auth session (Cookie headers).
+ * No mailer: sendInvitationEmail is unset; caller delivers claimUrl by hand.
+ */
+export async function createOrganizationInvitation(auth, opts) {
+    const raw = await callPluginApi(auth, 'createInvitation', {
+        body: {
+            email: opts.email.trim().toLowerCase(),
+            role: opts.role,
+            organizationId: opts.organizationId,
+        },
+        headers: opts.headers,
+    });
+    const invitation = parseInvitation(raw);
+    return {
+        invitationId: invitation.id,
+        claimUrl: invitationClaimUrl(opts.baseURL, invitation.id),
+        invitation,
+    };
+}
+/**
+ * Accept a pending invitation as the signed-in better-auth user (email must match).
+ * Single-use CAS: a second accept fails (maps to 410 at the route).
+ */
+export async function acceptOrganizationInvitation(auth, opts) {
+    const raw = await callPluginApi(auth, 'acceptInvitation', {
+        body: { invitationId: opts.invitationId },
+        headers: opts.headers,
+    });
+    if (!isRecord(raw) || !isRecord(raw.invitation) || !isRecord(raw.member)) {
+        throw new Error('acceptInvitation did not return invitation + member');
+    }
+    const invitation = parseInvitation(raw.invitation);
+    const member = raw.member;
+    if (typeof member.id !== 'string' ||
+        typeof member.organizationId !== 'string' ||
+        typeof member.userId !== 'string' ||
+        typeof member.role !== 'string') {
+        throw new Error('acceptInvitation member shape invalid');
+    }
+    return {
+        invitation,
+        member: {
+            id: member.id,
+            organizationId: member.organizationId,
+            userId: member.userId,
+            role: member.role,
+        },
+    };
+}
+/**
+ * Remove a member via better-auth (enforces ≥1 owner). Used by tests / future routes.
+ */
+export async function removeOrganizationMember(auth, opts) {
+    return callPluginApi(auth, 'removeMember', {
+        body: {
+            memberIdOrEmail: opts.memberIdOrEmail,
+            organizationId: opts.organizationId,
+        },
+        headers: opts.headers,
+    });
+}
+/**
+ * Update a member role via better-auth (enforces ≥1 owner on demote).
+ */
+export async function updateOrganizationMemberRole(auth, opts) {
+    return callPluginApi(auth, 'updateMemberRole', {
+        body: {
+            memberId: opts.memberId,
+            role: opts.role,
+            organizationId: opts.organizationId,
+        },
+        headers: opts.headers,
+    });
+}
+/** Mint a signed better-auth session cookie header for an existing user. */
+export async function mintSessionCookieHeader(auth, userId) {
+    const adapter = (await auth.$context).adapter;
+    const ctx = await auth.$context;
+    const now = new Date();
+    const token = `ba-sess-shell-${userId}-${Math.random().toString(36).slice(2)}`;
+    const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);
+    await adapter.create({
+        model: 'session',
+        data: {
+            userId,
+            token,
+            expiresAt,
+            createdAt: now,
+            updatedAt: now,
+        },
+    });
+    const signed = `${token}.${await makeSignature(token, ctx.secret)}`;
+    const headers = new Headers();
+    headers.set('cookie', `${ctx.authCookies.sessionToken.name}=${signed}`);
+    return headers;
+}
+/**
+ * Ensure a shell inviter user exists as owner of organizationId (REQ-3 bootstrap).
+ * Shell authority owns the DB — no interactive session required from the operator.
+ */
+export async function ensureShellOwner(auth, organizationId) {
+    const adapter = (await auth.$context).adapter;
+    const now = new Date();
+    let user = await adapter.findOne({
+        model: 'user',
+        where: [{ field: 'email', value: SHELL_EMAIL }],
+    });
+    if (user === null) {
+        user = await adapter.create({
+            model: 'user',
+            data: {
+                name: SHELL_NAME,
+                email: SHELL_EMAIL,
+                emailVerified: true,
+                image: null,
+                createdAt: now,
+                updatedAt: now,
+            },
+        });
+    }
+    const existing = await adapter.findMany({
+        model: 'member',
+        where: [
+            { field: 'userId', value: user.id },
+            { field: 'organizationId', value: organizationId },
+        ],
+    });
+    if (existing.length === 0) {
+        await adapter.create({
+            model: 'member',
+            data: {
+                organizationId,
+                userId: user.id,
+                role: 'owner',
+                createdAt: now,
+            },
+        });
+    }
+    const headers = await mintSessionCookieHeader(auth, user.id);
+    return { userId: user.id, headers };
+}
+/**
+ * Shell-side owner invitation for `plandesk admin invite-owner` (no GitHub, no mailer).
+ */
+export async function mintOwnerInvitation(auth, opts) {
+    const { headers } = await ensureShellOwner(auth, opts.organizationId);
+    const created = await createOrganizationInvitation(auth, {
+        email: opts.email,
+        role: 'owner',
+        organizationId: opts.organizationId,
+        headers,
+        baseURL: opts.baseURL,
+    });
+    return { invitationId: created.invitationId, claimUrl: created.claimUrl };
+}
+//# sourceMappingURL=invitations.js.map

package/dist/organizations.d.ts

@@ -0,0 +1,32 @@
+import type { BetterAuthInstance } from './better-auth.js';
+export type OrganizationSummary = {
+    id: string;
+    name: string;
+    slug: string;
+    createdAt: Date;
+};
+export type UserOrganizationSummary = {
+    id: string;
+    name: string;
+    role: string;
+};
+/**
+ * Look up a better-auth organization by id (user-less / server path).
+ * Prefer this over auth.api.getFullOrganization when no session headers exist.
+ */
+export declare function getOrganizationById(auth: BetterAuthInstance, organizationId: string): Promise<OrganizationSummary | undefined>;
+/**
+ * Loopback default org: DEFAULT_ORG_ID if present, else the sole organization.
+ */
+export declare function resolveDefaultOrganization(auth: BetterAuthInstance): Promise<OrganizationSummary | undefined>;
+export declare function listOrganizationsForUser(auth: BetterAuthInstance, userId: string): Promise<UserOrganizationSummary[]>;
+/**
+ * Display-friendly org for /auth/session and similar.
+ * Falls back to DEFAULT_ORG_ID → "Personal" when better-auth is not configured
+ * (loopback offline).
+ */
+export declare function resolveOrganizationName(auth: BetterAuthInstance | undefined, orgId: string): Promise<{
+    id: string;
+    name: string;
+}>;
+//# sourceMappingURL=organizations.d.ts.map

package/dist/organizations.js

@@ -0,0 +1,63 @@
+import { DEFAULT_ORG_ID } from '@plandesk/db';
+/**
+ * Look up a better-auth organization by id (user-less / server path).
+ * Prefer this over auth.api.getFullOrganization when no session headers exist.
+ */
+export async function getOrganizationById(auth, organizationId) {
+    const adapter = (await auth.$context).adapter;
+    const org = await adapter.findOne({
+        model: 'organization',
+        where: [{ field: 'id', value: organizationId }],
+    });
+    return org ?? undefined;
+}
+/**
+ * Loopback default org: DEFAULT_ORG_ID if present, else the sole organization.
+ */
+export async function resolveDefaultOrganization(auth) {
+    const byId = await getOrganizationById(auth, DEFAULT_ORG_ID);
+    if (byId !== undefined) {
+        return byId;
+    }
+    const adapter = (await auth.$context).adapter;
+    const all = await adapter.findMany({
+        model: 'organization',
+    });
+    if (all.length === 1) {
+        return all[0];
+    }
+    return undefined;
+}
+export async function listOrganizationsForUser(auth, userId) {
+    const adapter = (await auth.$context).adapter;
+    const members = await adapter.findMany({
+        model: 'member',
+        where: [{ field: 'userId', value: userId }],
+        sortBy: { field: 'createdAt', direction: 'asc' },
+    });
+    return Promise.all(members.map(async (member) => {
+        const organization = await getOrganizationById(auth, member.organizationId);
+        if (organization === undefined) {
+            throw new Error('Membership points to a missing organization');
+        }
+        return { id: organization.id, name: organization.name, role: member.role };
+    }));
+}
+/**
+ * Display-friendly org for /auth/session and similar.
+ * Falls back to DEFAULT_ORG_ID → "Personal" when better-auth is not configured
+ * (loopback offline).
+ */
+export async function resolveOrganizationName(auth, orgId) {
+    if (auth !== undefined) {
+        const org = await getOrganizationById(auth, orgId);
+        if (org !== undefined) {
+            return { id: org.id, name: org.name };
+        }
+    }
+    if (orgId === DEFAULT_ORG_ID) {
+        return { id: DEFAULT_ORG_ID, name: 'Personal' };
+    }
+    return { id: orgId, name: orgId };
+}
+//# sourceMappingURL=organizations.js.map

package/dist/permissions.d.ts

@@ -0,0 +1,19 @@
+import type { OrgRole } from '@plandesk/db';
+import { type statement } from './access-control.js';
+export type PermissionSet = Record<string, readonly string[]>;
+export type PermissionResource = keyof typeof statement;
+export type WorkAction = (typeof statement)['task'][number];
+/** Map better-auth org role directly onto the access-control statement sets. */
+export declare function orgRoleToPermissionSet(role: OrgRole): PermissionSet;
+export declare function hasPermission(permissions: PermissionSet, resource: string, action: string): boolean;
+export declare function hasAnyWritePermission(permissions: PermissionSet): boolean;
+/** Thrown when the caller lacks a specific resource:action → HTTP 403. */
+export declare class PermissionDeniedError extends Error {
+    readonly resource: string;
+    readonly action: string;
+    constructor(resource: string, action: string);
+}
+export declare function requirePermission(ctx: {
+    permission: PermissionSet;
+}, resource: string, action: string): void;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.js

@@ -0,0 +1,42 @@
+import { admin, member, owner, } from './access-control.js';
+const writeActions = new Set(['create', 'update', 'delete']);
+/** Map better-auth org role directly onto the access-control statement sets. */
+export function orgRoleToPermissionSet(role) {
+    switch (role) {
+        case 'member':
+            return member.statements;
+        case 'admin':
+            return admin.statements;
+        case 'owner':
+            return owner.statements;
+    }
+}
+export function hasPermission(permissions, resource, action) {
+    const actions = permissions[resource];
+    return actions !== undefined && actions.includes(action);
+}
+export function hasAnyWritePermission(permissions) {
+    for (const actions of Object.values(permissions)) {
+        if (actions.some((action) => writeActions.has(action))) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Thrown when the caller lacks a specific resource:action → HTTP 403. */
+export class PermissionDeniedError extends Error {
+    resource;
+    action;
+    constructor(resource, action) {
+        super(`requires ${resource}:${action}`);
+        this.name = 'PermissionDeniedError';
+        this.resource = resource;
+        this.action = action;
+    }
+}
+export function requirePermission(ctx, resource, action) {
+    if (!hasPermission(ctx.permission, resource, action)) {
+        throw new PermissionDeniedError(resource, action);
+    }
+}
+//# sourceMappingURL=permissions.js.map

package/dist/projection.d.ts

@@ -47,5 +47,5 @@ export type ClientView = {
         expires_at: string | null;
     };
 };
-export declare function buildClientView(db: Db, projectId: string, share: Share): ClientView | undefined;
+export declare function buildClientView(db: Db, projectId: string, share: Share): Promise<ClientView | undefined>;
 //# sourceMappingURL=projection.d.ts.map

package/dist/projection.js

@@ -6,14 +6,14 @@ function buildProgress(tasks) {
     }
     return progress;
 }
-export function buildClientView(db, projectId, share) {
-    const project = getProject(db, projectId);
+export async function buildClientView(db, projectId, share) {
+    const project = await getProject(db, projectId);
     if (!project) {
         return undefined;
     }
     const policy = parseSharePolicy(share);
     const permissions = parseSharePermissions(share);
-    const allTasks = listTasks(db, projectId);
+    const allTasks = await listTasks(db, projectId);
     const sharedTasks = [];
     for (const task of allTasks) {
         const included = policy.tasks === 'all' || (Array.isArray(policy.tasks) && policy.tasks.includes(task.id));
@@ -37,7 +37,7 @@ export function buildClientView(db, projectId, share) {
         sharedTasks.push(viewTask);
     }
     const sharedTaskIds = new Set(sharedTasks.map((task) => task.id));
-    const sharedEdges = listEdges(db, projectId)
+    const sharedEdges = (await listEdges(db, projectId))
         .filter((edge) => sharedTaskIds.has(edge.fromTaskId) && sharedTaskIds.has(edge.toTaskId))
         .map((edge) => ({
         id: edge.id,
@@ -46,7 +46,7 @@ export function buildClientView(db, projectId, share) {
         label: edge.label,
     }));
     const documentIdSet = new Set(policy.documentIds);
-    const sharedDocuments = listDocuments(db, projectId)
+    const sharedDocuments = (await listDocuments(db, projectId))
         .filter((doc) => documentIdSet.has(doc.id))
         .map((doc) => ({
         id: doc.id,

package/dist/routes/agent-runs.js

@@ -3,12 +3,12 @@ import { InvalidAgentRunError } from '../services/agent-runs.js';
 import { parsePaginationParams } from '../serialize.js';
 export function createAgentRunsRouter(agentRunService) {
     const router = new Hono();
-    router.get('/projects/:id/agent-runs', (c) => {
+    router.get('/projects/:id/agent-runs', async (c) => {
         const pagination = parsePaginationParams(c.req.query('limit'), c.req.query('offset'));
         if (pagination === 'invalid') {
             return c.json({ error: 'invalid_argument' }, 400);
         }
-        const runs = agentRunService.listForProject(c.req.param('id'), pagination);
+        const runs = await agentRunService.listForProject(c.req.param('id'), pagination);
         if (!runs) {
             return c.json({ error: 'not_found' }, 404);
         }
@@ -20,7 +20,7 @@ export function createAgentRunsRouter(agentRunService) {
             return c.json({ error: 'invalid_argument' }, 400);
         }
         try {
-            const event = agentRunService.recordProgress(c.req.param('id'), body.message);
+            const event = await agentRunService.recordProgress(c.req.param('id'), body.message);
             if (!event) {
                 return c.json({ error: 'not_found' }, 404);
             }

package/dist/routes/artifacts.js

@@ -6,8 +6,8 @@ function isValidKind(kind) {
 }
 export function createArtifactsRouter(artifactService) {
     const router = new Hono();
-    router.get('/projects/:id/artifacts', (c) => {
-        const artifacts = artifactService.listByProject(c.req.param('id'));
+    router.get('/projects/:id/artifacts', async (c) => {
+        const artifacts = await artifactService.listByProject(c.req.param('id'));
         if (!artifacts) {
             return c.json({ error: 'not_found' }, 404);
         }
@@ -22,7 +22,7 @@ export function createArtifactsRouter(artifactService) {
             return c.json({ error: 'invalid_argument' }, 400);
         }
         try {
-            const artifact = artifactService.create(c.req.param('id'), {
+            const artifact = await artifactService.create(c.req.param('id'), {
                 title: body.title,
                 kind: body.kind,
                 content: body.content,
@@ -39,8 +39,8 @@ export function createArtifactsRouter(artifactService) {
             throw error;
         }
     });
-    router.get('/artifacts/:id', (c) => {
-        const artifact = artifactService.get(c.req.param('id'));
+    router.get('/artifacts/:id', async (c) => {
+        const artifact = await artifactService.get(c.req.param('id'));
         if (!artifact) {
             return c.json({ error: 'not_found' }, 404);
         }
@@ -52,7 +52,7 @@ export function createArtifactsRouter(artifactService) {
             return c.json({ error: 'invalid_argument' }, 400);
         }
         try {
-            const artifact = artifactService.update(c.req.param('id'), {
+            const artifact = await artifactService.update(c.req.param('id'), {
                 ...(body.title !== undefined ? { title: body.title } : {}),
                 ...(body.kind !== undefined ? { kind: body.kind } : {}),
                 ...(body.content !== undefined ? { content: body.content } : {}),

package/dist/routes/auth.d.ts

@@ -0,0 +1,13 @@
+import { Hono } from 'hono';
+import type { Db } from '@plandesk/db';
+import type { BetterAuthInstance } from '../better-auth.js';
+import type { GithubConfig } from '../github.js';
+export type AuthRouterDeps = {
+    db: Db;
+    /** Absent on a self-hosted instance with no GitHub app registered (REQ-20). */
+    github?: GithubConfig;
+    /** better-auth instance for session-gated CLI owner-key mint (BA4b-2). */
+    betterAuth?: BetterAuthInstance;
+};
+export declare function createAuthRouter(deps: AuthRouterDeps): Hono;
+//# sourceMappingURL=auth.d.ts.map

package/dist/routes/auth.js

@@ -0,0 +1,83 @@
+import { Hono } from 'hono';
+import { createOrgOwnerKey } from '../agent-keys.js';
+import { getAuthContext } from '../auth-context.js';
+import { listOrganizationsForUser, resolveOrganizationName } from '../organizations.js';
+import { requirePermission } from '../permissions.js';
+export function createAuthRouter(deps) {
+    const router = new Hono();
+    const { github, betterAuth } = deps;
+    // What sign-in this instance offers.
+    //
+    // `githubEnabled` is for the dashboard: it decides between "Sign in with
+    // GitHub" and token entry. A self-hoster who never registered a GitHub app
+    // gets the token path (REQ-20). Device flow is gone — paste-a-token only.
+    router.get('/auth/methods', (c) => c.json({
+        method: 'token',
+        githubEnabled: github !== undefined,
+    }));
+    // Who the caller is right now, for the org/role badge and the sign-out
+    // control. Unauthenticated callers never reach this — org auth answers 401
+    // first, which is the dashboard's cue to show sign-in.
+    router.get('/auth/session', async (c) => {
+        const ctx = getAuthContext();
+        if (ctx.kind === 'guest') {
+            return c.json({ error: 'unauthorized' }, 401);
+        }
+        const org = await resolveOrganizationName(betterAuth, ctx.orgId);
+        let orgs = [
+            { id: org.id, name: org.name, role: ctx.role ?? 'member' },
+        ];
+        if (ctx.kind === 'session' && betterAuth !== undefined) {
+            const session = await betterAuth.api.getSession({ headers: c.req.raw.headers });
+            if (session === null) {
+                return c.json({ error: 'unauthorized' }, 401);
+            }
+            orgs = await listOrganizationsForUser(betterAuth, session.user.id);
+        }
+        return c.json({
+            kind: ctx.kind,
+            user_ref: ctx.kind === 'session' ? ctx.userRef : null,
+            role: ctx.role,
+            org,
+            orgs,
+        });
+    });
+    /**
+     * BA4b-2: mint an org-wide owner API key for CLI paste (`plandesk login`).
+     * Session-only — apikey/token/loopback must not mint owner keys here.
+     * Raw key returned once; never stored retrievable.
+     */
+    router.post('/auth/cli-token', async (c) => {
+        if (betterAuth === undefined) {
+            return c.json({ error: 'unavailable' }, 503);
+        }
+        const ctx = getAuthContext();
+        if (ctx.kind !== 'session') {
+            return c.json({ error: 'unauthorized' }, 401);
+        }
+        requirePermission(ctx, 'apiKey', 'create');
+        const baSession = await betterAuth.api.getSession({ headers: c.req.raw.headers });
+        if (baSession === null) {
+            return c.json({ error: 'unauthorized' }, 401);
+        }
+        let name = 'CLI token';
+        const body = (await c.req.json().catch(() => ({})));
+        if (typeof body.name === 'string' && body.name.trim() !== '') {
+            name = body.name.trim();
+        }
+        const minted = await createOrgOwnerKey({
+            auth: betterAuth,
+            userId: baSession.user.id,
+            orgId: ctx.orgId,
+            name,
+        });
+        const org = await resolveOrganizationName(betterAuth, ctx.orgId);
+        return c.json({
+            token: minted.key,
+            org_id: ctx.orgId,
+            org_name: org.name,
+        });
+    });
+    return router;
+}
+//# sourceMappingURL=auth.js.map

package/dist/routes/canvas.js

@@ -2,8 +2,8 @@ import { Hono } from 'hono';
 import { InvalidCanvasError } from '../services/canvas.js';
 export function createCanvasRouter(canvasService) {
     const router = new Hono();
-    router.get('/projects/:id/canvas', (c) => {
-        const canvas = canvasService.get(c.req.param('id'));
+    router.get('/projects/:id/canvas', async (c) => {
+        const canvas = await canvasService.get(c.req.param('id'));
         if (!canvas) {
             return c.json({ error: 'not_found' }, 404);
         }
@@ -31,7 +31,7 @@ export function createCanvasRouter(canvasService) {
             }
         }
         try {
-            const canvas = canvasService.putLayout(c.req.param('id'), {
+            const canvas = await canvasService.putLayout(c.req.param('id'), {
                 nodes: body.nodes,
                 edges: body.edges,
                 layout: body.layout,
@@ -48,8 +48,8 @@ export function createCanvasRouter(canvasService) {
             throw error;
         }
     });
-    router.delete('/projects/:id/edges/:edgeId', (c) => {
-        const deleted = canvasService.deleteEdge(c.req.param('id'), c.req.param('edgeId'));
+    router.delete('/projects/:id/edges/:edgeId', async (c) => {
+        const deleted = await canvasService.deleteEdge(c.req.param('id'), c.req.param('edgeId'));
         if (!deleted) {
             return c.json({ error: 'not_found' }, 404);
         }