boxel: Skill for Claude Code

The secure origin

The governing fact: the secure origin is exactly as safe as the least trusted thing it serves. It exists so that a credential typed into it can't be read by card code. The browser's same-origin policy does the isolating: the app page, and every card evaluated in it, can't read another origin's document, keystrokes or form values. That guarantee is about the origin, not the page. One script served anywhere on the origin, from any path, can read every window open on it. So the origin serves the pages packages/secure-origin builds — the shell, and the credential fields the app frames — and nothing else. No realm, card module, realm asset, host app bundle or third-party script, ever.

What it serves

• The shell, at the path of the configured URL (/ deployed, /secure in development): the built index.html, with no inline script, the files it loads (its entry point shell.js; the chunks that imports, among them shared.js with Ember and the components both entries use, the shell's own components staying in shell.js; layers.css, the order of the pages' cascade layers, which the build links ahead of every other stylesheet; and the components' stylesheets, shell.css among them with global.css's page-wide rules: boxel-ui's reset, the typeface and the page's background), and boxel-ui's variables.css, theme.css and the app's typeface, read from boxel-ui as they are. createSecureOrigin builds a routes table of every path served, from the build's manifest (see below).
• Modes are added to shell.js's modes table, keyed by the mode query parameter. Every mode is the same shell document, with the same headers. They are sign-in, cli-sign-in (boxel keys sign-in) and cli-auth (boxel profile add, which hands the CLI a Matrix login token; see the secure-session skill) (components in src/shell/sign-in/, mounted with renderComponent), register and verify-email, where a registration email's link lands (src/shell/register/), and forgot-password and reset-password, where a reset email's link lands (src/shell/password-reset/); Google returns to google-callback, which serves the shell too. sign-out ends the window's session and goes back to the app page in its #return=. An unknown mode renders nothing. A sign-in the app started carries #return= too, and the window hands it back with a login token (the secure-session skill); return is honoured only on an origin in the shell's boxel-app-origins markup, which the realm server fills with the credential fields' app origins.
• The pages are the app's sign-in screens, the same components in both places, and every one is a Glimmer component. src/components/ holds AuthContainer, AuthButton and AuthFormField and ports of the boxel-ui components they use (Button, FieldContainer, Label, BoxelInput, InputGroup, LoadingIndicator and the icons), each with boxel-ui's scoped CSS. src/screens/ holds the screens themselves, presentational and stateless: sign-in, the registration steps and the password-reset steps, each taking its values and actions as arguments and its password fields as a block. The host renders its Login, RegisterUser and ForgotPassword from these, with its own controller (the Matrix service, the router) and the credential frame as the password fields (ADR 008 §1.9); the host may import from the package, and the package never imports from the host. On the secure origin, src/shell/sign-in/ holds the sign-in form's controller, the CLI sign-in, the Google callback and the pages a sign-in ends on; src/shell/register/ and src/shell/password-reset/ hold account creation and password reset, with the host's RegisterUser and ForgotPassword rules, and render the same screens with the package's own inputs. The decisions behind them are plain modules: the CLI's loopback target and hand-off (src/security/cli-handoff.js), the registration's stages and the new account's first sign-in (src/security/registration.ts), and the reset link (src/shell/password-reset/reset-link.ts). The icon components copy boxel-ui's paths for the logo, Google's "G", the check mark and the spinner. A change to one of these screens' look or copy is made once, in the package, and reaches both origins. The CLI sign-in pages, the app's (cli-auth.gts) and the secure origin's (src/shell/sign-in/cli-auth-page.gts), render the sign-in screen too, naming themselves with the screen's @title and saying what signing in grants the CLI in its intro block, whose type and spacing the screen sets. Each screen's controls carry both origins' test attributes (data-test-login-btn beside data-test-secure-password-submit, and so on), so keep both when editing one.