@ikenga/contract 0.3.0

package/src/rpc.ts

@@ -0,0 +1,97 @@
+// Shell ↔ pkg RPC. Same envelope on both transports:
+//  - iframe pkgs: postMessage over MessageChannel
+//  - mounted pkgs: direct function call on the host bus
+//
+// Methods are namespaced by capability area. The kernel enforces scopes
+// declared in the pkg manifest before dispatching.
+
+export const CONTRACT_VERSION = 1 as const;
+
+// ---------- Envelope ----------
+
+export interface RpcRequest<TParams = unknown> {
+  v: typeof CONTRACT_VERSION;
+  id: string;
+  method: string;
+  params: TParams;
+}
+
+export interface RpcResponseOk<TResult = unknown> {
+  v: typeof CONTRACT_VERSION;
+  id: string;
+  result: TResult;
+}
+
+export interface RpcResponseErr {
+  v: typeof CONTRACT_VERSION;
+  id: string;
+  error: { code: RpcErrorCode; message: string; data?: unknown };
+}
+
+export type RpcResponse<T = unknown> = RpcResponseOk<T> | RpcResponseErr;
+export type RpcMessage = RpcRequest | RpcResponse;
+
+export type RpcErrorCode =
+  | 'method_not_found'
+  | 'invalid_params'
+  | 'scope_denied'
+  | 'pkg_not_authenticated'
+  | 'shell_unavailable'
+  | 'internal_error';
+
+// ---------- Notifications (one-way, pkg → shell or shell → pkg) ----------
+
+export interface RpcNotification<TParams = unknown> {
+  v: typeof CONTRACT_VERSION;
+  notify: string;
+  params: TParams;
+}
+
+// ---------- Method catalogue ----------
+//
+// Adding a method is a contract change. Removals require a deprecation
+// period across two contract minor versions.
+
+export interface RpcMethods {
+  // identity
+  'identity.whoami': { req: void; res: { user_id: string; tenant_id: string | null } };
+
+  // pkg → engine
+  'engine.start_session': {
+    req: { systemPrompt?: string; toolAllowList?: string[] };
+    res: { sessionId: string };
+  };
+  'engine.stream': {
+    req: { sessionId: string; input: string };
+    res: { ok: true }; // events delivered via 'engine.event' notifications
+  };
+  'engine.cancel': { req: { sessionId: string }; res: { ok: true } };
+
+  // shell chrome
+  'shell.notify': { req: { title: string; body?: string; level?: 'info' | 'warn' | 'error' }; res: void };
+  'shell.open_pane': {
+    req: { route?: string; pkg_id?: string; split?: 'horizontal' | 'vertical' };
+    res: { pane_id: string };
+  };
+
+  // tasks (capability: tasks:read / tasks:write)
+  'tasks.list': { req: { status?: string; owner?: string }; res: unknown[] };
+  'tasks.create': { req: { subject: string; description?: string }; res: { id: string } };
+
+  // email drafts
+  'email_drafts.list': { req: { status?: string }; res: unknown[] };
+  'email_drafts.create': { req: { subject: string; body_html: string; to: string[] }; res: { id: string } };
+}
+
+// Notifications: shell → pkg
+export interface ShellToPkgNotifications {
+  'engine.event': { sessionId: string; event: import('./engine.js').EngineEvent };
+  'shell.theme_changed': { theme: 'light' | 'dark' };
+  'shell.pane_focused': { focused: boolean };
+}
+
+// ---------- Helpers ----------
+
+export type RpcMethodName = keyof RpcMethods;
+export type RpcParams<M extends RpcMethodName> = RpcMethods[M]['req'];
+export type RpcResult<M extends RpcMethodName> = RpcMethods[M]['res'];

package/src/scopes.ts

@@ -0,0 +1,71 @@
+// Capability scopes a pkg can request in its manifest. The kernel enforces
+// these at the IPC boundary — scope-denied requests fail with
+// `RpcErrorCode.scope_denied` before reaching the handler.
+//
+// Scope syntax: `<resource>:<action>` or `<resource>:<action>:<qualifier>`
+//
+// Pattern wildcards are allowed in qualifiers only:
+//   "fs:read:projects/*"   ✓  (file under /projects/)
+//   "tasks:*"              ✗  (action wildcards forbidden — be explicit)
+
+export interface ScopeDef {
+  scope: string;
+  description: string;
+  /** Whether this scope requires explicit user consent at install time. */
+  sensitive?: boolean;
+}
+
+export const SCOPE_CATALOGUE: ScopeDef[] = [
+  // identity
+  { scope: 'identity:read', description: 'Read the current user / tenant identity.' },
+
+  // tasks
+  { scope: 'tasks:read', description: 'List and read tasks.' },
+  { scope: 'tasks:write', description: 'Create, update, complete tasks.' },
+
+  // contacts
+  { scope: 'contacts:read', description: 'Read the contacts directory.' },
+  { scope: 'contacts:write', description: 'Create or update contacts.', sensitive: true },
+
+  // email
+  { scope: 'email_drafts:read', description: 'Read drafts in the email queue.' },
+  { scope: 'email_drafts:write', description: 'Create or modify drafts.' },
+  { scope: 'email:send', description: 'Send email through the shell delivery layer.', sensitive: true },
+
+  // social
+  { scope: 'social:read', description: 'Read queued and posted social items.' },
+  { scope: 'social:publish', description: 'Publish to connected social accounts.', sensitive: true },
+
+  // filesystem (shell-mediated)
+  { scope: 'fs:read', description: 'Read files inside the shell-managed sandbox.' },
+  { scope: 'fs:write', description: 'Write files inside the shell-managed sandbox.', sensitive: true },
+
+  // engine
+  { scope: 'engine:invoke', description: 'Start sessions and stream from the active AI engine.' },
+  { scope: 'engine:register_mcp', description: 'Register additional MCP servers with the engine.', sensitive: true },
+
+  // shell chrome
+  { scope: 'shell:notify', description: 'Show notifications in the shell UI.' },
+  { scope: 'shell:open_pane', description: 'Open or split panes in the shell layout.' },
+];
+
+const SCOPE_INDEX = new Map(SCOPE_CATALOGUE.map((s) => [s.scope, s]));
+
+export function isKnownScope(scope: string): boolean {
+  if (SCOPE_INDEX.has(scope)) return true;
+  // Allow qualified variants (`fs:read:projects/*`) only if the unqualified
+  // form is in the catalogue.
+  const parts = scope.split(':');
+  if (parts.length < 3) return false;
+  return SCOPE_INDEX.has(`${parts[0]}:${parts[1]}`);
+}
+
+export function isSensitiveScope(scope: string): boolean {
+  const def = SCOPE_INDEX.get(scope);
+  if (def) return !!def.sensitive;
+  const parts = scope.split(':');
+  if (parts.length < 3) return false;
+  return !!SCOPE_INDEX.get(`${parts[0]}:${parts[1]}`)?.sensitive;
+}
+
+export type Scope = string;