synqauth 0.0.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aerosol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,38 @@
 # synqauth
 
-Synq's CLI: npx synqauth init gives your app a working sign-in. This placeholder holds the name until the first release.
+Synq's command line. `npx synqauth init` gives your Next.js app a working sign-in, with no account: try Synq on your laptop first, and claim it when you sign up.
 
-https://synq.build
+Synq is customer identity for businesses: an OpenID Connect issuer for each of your brands, with social, email, passkey and Solana wallet sign-in. The documentation is at [docs.synq.build](https://docs.synq.build).
+
+This package is at 0.x: its commands can change in any release until Synq's first customer depends on it.
+
+## `npx synqauth init`
+
+Run it in a Next.js App Router project (an `app/` or `src/app/` folder):
+
+```sh
+npx synqauth init
+```
+
+It asks Synq for a development sign-in: an org of your own with one app, on `https://localhost:<your dev port>` only, named after your package (`@acme/web` is `acme-web`). Then it:
+
+- writes the app's keys to `.env.local` (`SYNQ_ISSUER`, `SYNQ_CLIENT_ID`, `SYNQ_CLIENT_SECRET`, `SYNQ_APP_URL`, `SYNQ_SESSION_SECRET` and `SYNQ_CLAIM_TOKEN`), and makes sure git ignores it: it adds `.env*.local` to your app's `.gitignore` only where git doesn't ignore the file already (outside a git repo, where `.gitignore` doesn't say so)
+- adds `@synqauth/nextjs` with your package manager
+- adds `synq.config.ts`, `lib/synq.ts`, the route mount at `app/api/auth/[...synq]/route.ts`, and a page at `/synq` that signs you in and shows who
+- makes your `dev` script serve https (`next dev --experimental-https`), which Synq's development redirect URIs need
+
+It never overwrites a file you have, and stops before making anything when `.env.local` already has Synq's values (`--force` makes another).
+
+Start your app and open `https://localhost:3000/synq` to sign in. Its first start may ask for your computer's password, once, to trust a local certificate: Next.js makes its https certificate with mkcert. Accept it, since sign-in needs the https address. Where the prompt can't be answered (a shell with no terminal, an agent, CI), Next.js serves `http://localhost:3000` instead, and the `/synq` page says to restart `dev` in a terminal and accept the prompt. To keep the sign-in, open the claim link it prints (it's also in `.env.local`) within 7 days and sign up: the org is yours, with no limits but your plan's. Until then it signs in up to 25 people, on localhost only, and Synq deletes it if nobody claims it.
+
+`npm create synq` does the same.
+
+Options:
+
+- `--force`: make another development sign-in, even where `.env.local` has Synq's values
+- `--no-install`: don't add `@synqauth/nextjs`
+- `--stage preview|local`: for working on Synq itself; `local` reads `SYNQ_API_URL` and `SYNQ_WEBSITE_URL`
+
+## License
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/bin.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { t as main } from "./cli-C7dDFb81.js";
+//#region src/bin.ts
+process.exitCode = await main(process.argv.slice(2));
+//#endregion
+export {};

package/dist/cli-C7dDFb81.js

@@ -0,0 +1,950 @@
+import { parseArgs } from "node:util";
+import { spawn, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { closeSync, constants, existsSync, fchmodSync, lstatSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, posix, relative } from "node:path";
+//#region src/api.ts
+/** Why Synq didn't make one, in words for the developer. */
+var SynqApiError = class extends Error {
+	code;
+	status;
+	constructor(message, code, status) {
+		super(message);
+		this.name = "SynqApiError";
+		this.code = code;
+		this.status = status;
+	}
+};
+async function createClaimableOrg(api, request, options) {
+	const send = options.fetch ?? fetch;
+	let res;
+	try {
+		res = await send(new URL("/v1/claimable-orgs", api), {
+			method: "POST",
+			signal: AbortSignal.timeout(15e3),
+			redirect: "error",
+			headers: {
+				"content-type": "application/json",
+				"user-agent": options.userAgent
+			},
+			body: JSON.stringify({
+				name: request.name,
+				app_type: request.appType,
+				redirect_uris: request.redirectUris,
+				post_logout_redirect_uris: request.postLogoutRedirectUris
+			})
+		});
+	} catch {
+		throw new SynqApiError(`Couldn't reach Synq at ${api}. Check your connection and try again.`, "network");
+	}
+	if (res.status === 201) {
+		const made = await res.json().catch(() => void 0);
+		if (!isClaimableOrg(made)) throw new SynqApiError("Synq returned an incomplete development sign-in. No credentials were written; try again later.", "invalid_response", 201);
+		return made;
+	}
+	const problem = await res.json().catch(() => ({})) ?? {};
+	const code = [
+		"rate_limited",
+		"org_creation_closed",
+		"validation_failed"
+	].includes(String(problem.code)) ? String(problem.code) : `http_${res.status}`;
+	if (res.status === 429) {
+		const wait = Number(res.headers.get("retry-after"));
+		throw new SynqApiError(`Synq makes a few development sign-ins a day from one address, and this one has had them.${Number.isFinite(wait) && wait > 0 ? ` Try again in ${wait >= 3600 ? `${Math.ceil(wait / 3600)} hours` : `${Math.ceil(wait / 60)} minutes`}` : " Try again later"}, or sign up at ${options.website} to make an app in the dashboard.`, code, 429);
+	}
+	if (code === "org_creation_closed") throw new SynqApiError(`Synq can't make a development sign-in here yet. Sign up at ${options.website} to make an app in the dashboard.`, code, res.status);
+	throw new SynqApiError(`Synq refused (${code}). Check the project name and localhost redirect settings, then try again.`, code, res.status);
+}
+/** Check the one-time credentials before writing anything into a project. */
+function isClaimableOrg(value) {
+	const object = (v) => typeof v === "object" && v !== null;
+	const text = (v) => typeof v === "string" && v.length > 0 && !v.includes("$") && [...v].every((char) => char.charCodeAt(0) >= 32 && char.charCodeAt(0) !== 127);
+	const url = (v) => text(v) && URL.canParse(v) && (new URL(v).protocol === "https:" || new URL(v).protocol === "http:" && /^(localhost|127\.0\.0\.1|\[::1\])$/.test(new URL(v).hostname)) && !new URL(v).username && !new URL(v).password;
+	if (!object(value)) return false;
+	const { org, app, claim, limits } = value;
+	return object(org) && text(org.id) && text(org.slug) && text(org.name) && url(value.issuer) && object(app) && text(app.client_id) && text(app.client_secret) && Array.isArray(app.redirect_uris) && app.redirect_uris.every(url) && object(claim) && text(claim.token) && /^synq_claim_[A-Za-z0-9_-]{43}$/.test(claim.token) && (claim.url === null || url(claim.url)) && text(claim.expires_at) && Number.isFinite(Date.parse(claim.expires_at)) && object(limits) && typeof limits.users === "number" && Number.isSafeInteger(limits.users) && limits.users > 0;
+}
+Object.freeze({
+	mainnet: "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d",
+	devnet: "EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG",
+	testnet: "4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY"
+});
+//#endregion
+//#region ../links/src/host-map.ts
+const HOST_MAP = [
+	{
+		product: "aerosol",
+		surface: "website",
+		production: ["https://www.aerosol.build", "https://aerosol.build"],
+		staging: null,
+		preview: "https://preview.aerosol.build"
+	},
+	{
+		product: "burn-and-claim",
+		surface: "admin",
+		production: ["https://admin.burnandclaim.com"],
+		staging: null,
+		preview: "https://preview-admin.burnandclaim.com"
+	},
+	{
+		product: "burn-and-claim",
+		surface: "analytics",
+		production: ["https://analytics.burnandclaim.com"],
+		staging: null,
+		preview: "https://preview-analytics.burnandclaim.com"
+	},
+	{
+		product: "burn-and-claim",
+		surface: "api",
+		production: ["https://api.burnandclaim.com"],
+		staging: null,
+		preview: "https://preview-api.burnandclaim.com"
+	},
+	{
+		product: "burn-and-claim",
+		surface: "app",
+		production: ["https://app.burnandclaim.com"],
+		staging: "https://staging-app.burnandclaim.com",
+		preview: "https://preview-app.burnandclaim.com"
+	},
+	{
+		product: "burn-and-claim",
+		surface: "dashboard",
+		production: ["https://dashboard.burnandclaim.com"],
+		staging: null,
+		preview: "https://preview-dashboard.burnandclaim.com"
+	},
+	{
+		product: "burn-and-claim",
+		surface: "docs",
+		production: ["https://docs.burnandclaim.com"],
+		staging: null,
+		preview: "https://preview-docs.burnandclaim.com"
+	},
+	{
+		product: "burn-and-claim",
+		surface: "domains",
+		production: ["https://domains.burnandclaim.com"],
+		staging: null,
+		preview: "https://preview-domains.burnandclaim.com"
+	},
+	{
+		product: "burn-and-claim",
+		surface: "media",
+		production: ["https://media.burnandclaim.com"],
+		staging: null,
+		preview: "https://preview-media.burnandclaim.com"
+	},
+	{
+		product: "burn-and-claim",
+		surface: "website",
+		production: [
+			"https://www.burnandclaim.com",
+			"https://burnandclaim.com",
+			"https://beta-website.burnandclaim.com"
+		],
+		staging: null,
+		preview: "https://preview.burnandclaim.com"
+	},
+	{
+		product: "mollyverse",
+		surface: "website",
+		production: ["https://www.mollyverse.art", "https://mollyverse.art"],
+		staging: "https://staging.mollyverse.art",
+		preview: "https://preview.mollyverse.art"
+	},
+	{
+		product: "rodai",
+		surface: "api",
+		production: ["https://api.rodai.meme"],
+		staging: null,
+		preview: "https://preview-api.rodai.meme"
+	},
+	{
+		product: "rodai",
+		surface: "website",
+		production: ["https://www.rodai.meme", "https://rodai.meme"],
+		staging: null,
+		preview: "https://preview.rodai.meme"
+	},
+	{
+		product: "seed-my-wallet",
+		surface: "api",
+		production: ["https://api.seedmywallet.com"],
+		staging: null,
+		preview: "https://preview-api.seedmywallet.com"
+	},
+	{
+		product: "seed-my-wallet",
+		surface: "app",
+		production: ["https://app.seedmywallet.com"],
+		staging: null,
+		preview: "https://preview-app.seedmywallet.com"
+	},
+	{
+		product: "seed-my-wallet",
+		surface: "faucet",
+		production: ["https://faucet.seedmywallet.com"],
+		staging: null,
+		preview: "https://preview-faucet.seedmywallet.com"
+	},
+	{
+		product: "seed-my-wallet",
+		surface: "website",
+		production: ["https://www.seedmywallet.com", "https://seedmywallet.com"],
+		staging: null,
+		preview: "https://preview.seedmywallet.com"
+	},
+	{
+		product: "spotlight",
+		surface: "admin",
+		production: ["https://admin.spotlightads.app"],
+		staging: null,
+		preview: null
+	},
+	{
+		product: "spotlight",
+		surface: "api",
+		production: ["https://api.spotlightads.app"],
+		staging: null,
+		preview: "https://preview-api.spotlightads.app"
+	},
+	{
+		product: "spotlight",
+		surface: "app",
+		production: ["https://app.spotlightads.app"],
+		staging: null,
+		preview: null
+	},
+	{
+		product: "spotlight",
+		surface: "docs",
+		production: ["https://docs.spotlightads.app"],
+		staging: null,
+		preview: null
+	},
+	{
+		product: "spotlight",
+		surface: "media",
+		production: ["https://media.spotlightads.app"],
+		staging: null,
+		preview: "https://preview-media.spotlightads.app"
+	},
+	{
+		product: "spotlight",
+		surface: "website",
+		production: ["https://spotlightads.app", "https://www.spotlightads.app"],
+		staging: null,
+		preview: "https://preview.spotlightads.app"
+	},
+	{
+		product: "synq",
+		surface: "accounts",
+		production: ["https://accounts.synq.build"],
+		staging: null,
+		preview: "https://preview-accounts.synq.build"
+	},
+	{
+		product: "synq",
+		surface: "admin",
+		production: ["https://admin.synq.build"],
+		staging: null,
+		preview: "https://preview-admin.synq.build"
+	},
+	{
+		product: "synq",
+		surface: "api",
+		production: ["https://api.synq.build"],
+		staging: null,
+		preview: "https://preview-api.synq.build"
+	},
+	{
+		product: "synq",
+		surface: "auth",
+		production: ["https://auth.synq.build"],
+		staging: null,
+		preview: "https://preview-auth.synq.build"
+	},
+	{
+		product: "synq",
+		surface: "dashboard",
+		production: ["https://dashboard.synq.build"],
+		staging: null,
+		preview: "https://preview-dashboard.synq.build"
+	},
+	{
+		product: "synq",
+		surface: "demo",
+		production: ["https://demo.synq.build"],
+		staging: null,
+		preview: "https://preview-demo.synq.build"
+	},
+	{
+		product: "synq",
+		surface: "docs",
+		production: ["https://docs.synq.build"],
+		staging: null,
+		preview: "https://preview-docs.synq.build"
+	},
+	{
+		product: "synq",
+		surface: "domains",
+		production: ["https://domains.synq.build"],
+		staging: null,
+		preview: "https://preview-domains.synq.build"
+	},
+	{
+		product: "synq",
+		surface: "media",
+		production: ["https://media.synq.build"],
+		staging: null,
+		preview: "https://preview-media.synq.build"
+	},
+	{
+		product: "synq",
+		surface: "website",
+		production: ["https://synq.build", "https://www.synq.build"],
+		staging: null,
+		preview: "https://preview.synq.build"
+	}
+];
+/** The site this copy is built into: the only line that differs between repos. */
+const THIS_SITE = {
+	product: "synq",
+	surface: "website"
+};
+(() => {
+	const entry = HOST_MAP.find((candidate) => candidate.product === THIS_SITE.product && candidate.surface === THIS_SITE.surface);
+	if (!entry) throw new Error(`host-map.ts: no entry for ${THIS_SITE.product} ${THIS_SITE.surface}`);
+	return entry;
+})();
+//#endregion
+//#region ../links/src/environment.ts
+const STAGES = [
+	"local",
+	"preview",
+	"staging",
+	"production"
+];
+const isStage = (value) => typeof value === "string" && STAGES.includes(value);
+/**
+* The variable a local stack sets for a surface's origin, since the host map
+* has no local hosts: `<PRODUCT>_<SURFACE>_URL` in upper case, dashes as
+* underscores (`SYNQ_API_URL`, `SEED_MY_WALLET_API_URL`).
+*/
+function localOriginVariable(product, surface) {
+	return `${product}_${surface}_URL`.toUpperCase().replace(/-/g, "_");
+}
+/** `value` as an http(s) origin, or undefined when it is anything more or less than one. */
+function originOf(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return;
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") return void 0;
+	if (url.username || url.password || url.pathname !== "/" || url.search || url.hash) return void 0;
+	return url.origin;
+}
+function entryFor(product, surface) {
+	const entry = HOST_MAP.find((e) => e.product === product && e.surface === surface);
+	if (!entry) throw new Error(`host-map.ts has no ${product} ${surface}: give it a row in every repo's copy at once (AERO-1528)`);
+	return entry;
+}
+/**
+* HOST_MAP's origin for a surface in a stage: production[0], staging or
+* preview. Local takes the override the AppHost sets,
+* `<PRODUCT>_<SURFACE>_URL` (localOriginVariable). Throws when there is none:
+* a stage never falls back to another stage's host.
+*/
+function originFor(product, surface, stage, env = {}) {
+	if (!isStage(stage)) throw new Error(`The stage must be one of ${STAGES.join(", ")}`);
+	const entry = entryFor(product, surface);
+	if (stage === "local") {
+		const variable = localOriginVariable(product, surface);
+		const value = env[variable]?.trim();
+		if (!value) throw new Error(`${variable} must be set locally: the host map has no local hosts`);
+		const origin = originOf(value);
+		if (!origin) throw new Error(`${variable} must be an http:// or https:// origin`);
+		return origin;
+	}
+	const origin = stage === "production" ? entry.production[0] : entry[stage];
+	if (!origin) throw new Error(`host-map.ts gives ${product} ${surface} no ${stage} host`);
+	return origin;
+}
+/** The API a stage reads: its own, and production's for staging (AERO-1526). */
+function apiOriginFor(product, stage, env = {}) {
+	return originFor(product, "api", stage === "staging" ? "production" : stage, env);
+}
+//#endregion
+//#region src/env.ts
+/** The names `synqauth init` writes. One already set means the project has Synq. */
+const SYNQ_VARIABLES = [
+	"SYNQ_ISSUER",
+	"SYNQ_CLIENT_ID",
+	"SYNQ_CLIENT_SECRET",
+	"SYNQ_APP_URL",
+	"SYNQ_SESSION_SECRET",
+	"SYNQ_CLAIM_TOKEN"
+];
+/** The names set in an env file's text: `NAME=…`, `export NAME=…`, never a comment. */
+function namesIn(text) {
+	const names = /* @__PURE__ */ new Set();
+	for (const line of text.split(/\r?\n/)) {
+		const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+		if (match) names.add(match[1]);
+	}
+	return names;
+}
+/** The variables of `SYNQ_VARIABLES` the text sets already. */
+function synqNamesIn(text) {
+	const names = namesIn(text);
+	return SYNQ_VARIABLES.filter((name) => names.has(name));
+}
+/** A value as a dotenv line takes it: quoted when it has anything but plain characters. */
+function quoted(value) {
+	return /^[A-Za-z0-9_./:@+=-]*$/.test(value) ? value : JSON.stringify(value);
+}
+/**
+* `existing` with Synq's block appended: the comment, then each value. The
+* existing text is kept byte for byte, with a newline added only if it
+* lacks a last one.
+*/
+function withSynqBlock(existing, values, comment) {
+	const head = existing === "" || existing.endsWith("\n") ? existing : `${existing}\n`;
+	return `${head}${head === "" ? "" : "\n"}${[...comment.map((line) => `# ${line}`), ...SYNQ_VARIABLES.map((name) => `${name}=${quoted(values[name])}`)].join("\n")}\n`;
+}
+/** Whether a `.gitignore`'s text keeps `.env.local` out of git. */
+function ignoresEnvLocal(gitignore) {
+	let ignored = false;
+	for (const line of gitignore.split(/\r?\n/).map((line) => line.trim())) {
+		if (line.startsWith("!")) ignored = false;
+		if ([
+			".env.local",
+			".env*.local",
+			".env*",
+			".env.*",
+			"*.local",
+			"/.env.local",
+			"/.env*.local"
+		].includes(line)) ignored = true;
+	}
+	return ignored;
+}
+/** `.gitignore`'s text with `.env*.local` added, when it doesn't ignore `.env.local` yet. */
+function withEnvLocalIgnored(gitignore) {
+	return ignoresEnvLocal(gitignore) ? void 0 : withEnvLocalLine(gitignore);
+}
+/** `.gitignore`'s text with `.env*.local` added under a comment, keeping every byte it had. */
+function withEnvLocalLine(gitignore) {
+	const head = gitignore === "" || gitignore.endsWith("\n") ? gitignore : `${gitignore}\n`;
+	return `${head}${head === "" ? "" : "\n"}# Local secrets, such as Synq's (npx synqauth init)\n.env*.local\n`;
+}
+//#endregion
+//#region src/nextjs.ts
+/**
+* The files for a project whose App Router folder is `appDir` (`app` or
+* `src/app`), pointing at `docs`, Synq's documentation. The /synq page names
+* `dev`'s address and command for when it's served over http.
+*/
+function nextjsFiles(appDir, docs, dev) {
+	const base = appDir === "src/app" ? "src" : "";
+	const lib = posix.join(base, "lib", "synq.ts");
+	const route = posix.join(appDir, "api", "auth", "[...synq]", "route.ts");
+	const page = posix.join(appDir, "synq", "page.tsx");
+	const importOf = (from, to) => {
+		const relative = posix.relative(posix.dirname(from), to).replace(/\.tsx?$/, "");
+		return relative.startsWith(".") ? relative : `./${relative}`;
+	};
+	return [
+		{
+			path: "synq.config.ts",
+			why: "the configuration the server and a proxy share",
+			contents: [
+				"import { defineSynqConfig } from '@synqauth/nextjs/config'",
+				"",
+				"// Synq's settings: it reads SYNQ_ISSUER, SYNQ_CLIENT_ID, SYNQ_CLIENT_SECRET,",
+				`// SYNQ_APP_URL and SYNQ_SESSION_SECRET from .env.local. ${docs}`,
+				"export const synqConfig = defineSynqConfig({})",
+				""
+			].join("\n")
+		},
+		{
+			path: lib,
+			why: "Synq on your server: `await synq.me()` is who is signed in",
+			contents: [
+				"import { synqAuth } from '@synqauth/nextjs'",
+				"",
+				`import { synqConfig } from '${importOf(lib, "synq.config.ts")}'`,
+				"",
+				"export const synq = synqAuth(synqConfig)",
+				""
+			].join("\n")
+		},
+		{
+			path: route,
+			why: "the route mount: sign-in, the callback and sign-out under /api/auth",
+			contents: [
+				`import { synq } from '${importOf(route, lib)}'`,
+				"",
+				"export const { GET, POST, PATCH, DELETE } = synq.handlers",
+				""
+			].join("\n")
+		},
+		{
+			path: page,
+			why: "a page at /synq that signs you in and shows who: delete it once your own pages do",
+			contents: [
+				"import { headers } from 'next/headers'",
+				"",
+				`import { synq } from '${importOf(page, lib)}'`,
+				"",
+				"// Made by `npx synqauth init` to show Synq signing someone in to this app.",
+				`// Delete it once your own pages sign people in. ${docs}`,
+				"const style = { fontFamily: 'system-ui, sans-serif', maxWidth: 32 * 16, margin: '4rem auto', lineHeight: 1.5 }",
+				"",
+				"export default async function SynqPage() {",
+				"  // `next dev --experimental-https` serves http when it couldn't trust its",
+				"  // local certificate. Synq sends people back to the https address only.",
+				"  if ((await headers()).get('x-forwarded-proto') === 'http') {",
+				"    return (",
+				"      <main style={style}>",
+				"        <h1>Sign-in needs https</h1>",
+				"        <p>",
+				"          {\"This page is on http: the dev server couldn't trust its local certificate, so sign-in can't finish.\"}",
+				"        </p>",
+				"        <p>",
+				`          Stop the dev server, start it again in a terminal with <code>${dev.command}</code>, and accept`,
+				"          the prompt for your password. It asks once, to trust a local certificate. Then open{' '}",
+				`          <a href="${dev.appUrl}/synq">${dev.appUrl}/synq</a>.`,
+				"        </p>",
+				"      </main>",
+				"    )",
+				"  }",
+				"  const me = await synq.me()",
+				"  return (",
+				"    <main style={style}>",
+				"      <h1>{me ? \"It works: you're signed in\" : 'Sign in with Synq'}</h1>",
+				"      {me ? (",
+				"        <>",
+				"          <p>Signed in as {me.email ?? me.name ?? me.sub}.</p>",
+				"          <form method=\"post\" action={synq.signOutPath}>",
+				"            <button type=\"submit\">Sign out</button>",
+				"          </form>",
+				"        </>",
+				"      ) : (",
+				"        <p>",
+				"          <a href={synq.signInPath({ returnTo: '/synq' })}>Sign in</a>",
+				"        </p>",
+				"      )}",
+				"    </main>",
+				"  )",
+				"}",
+				""
+			].join("\n")
+		}
+	];
+}
+/**
+* A dev script that serves https, which Synq's development redirect URIs
+* need (`https://localhost:3000/...`): `next dev` gains
+* `--experimental-https`. Undefined when it has it already, or isn't
+* `next dev`.
+*/
+function httpsDevScript(script) {
+	if (!script || !/\bnext\s+dev\b/.test(script) || /--experimental-https\b/.test(script)) return;
+	return script.replace(/\bnext\s+dev\b/, "next dev --experimental-https");
+}
+//#endregion
+//#region src/project.ts
+const DEFAULT_PORTS = {
+	nextjs: 3e3,
+	vite: 5173,
+	unknown: 3e3
+};
+/** Reads the project in `dir`. */
+function readProject(dir) {
+	const manifest = readManifest(dir);
+	const framework = frameworkOf(manifest);
+	const appDir = framework === "nextjs" ? ["app", "src/app"].find((candidate) => existsSync(join(dir, candidate))) : void 0;
+	return {
+		dir,
+		name: projectName(manifest?.name, basename(dir)),
+		framework,
+		appDir,
+		packageManager: packageManagerOf(dir),
+		port: portOf(manifest?.scripts?.dev, framework),
+		manifest
+	};
+}
+function readManifest(dir) {
+	try {
+		return JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+	} catch {
+		return;
+	}
+}
+function frameworkOf(manifest) {
+	const deps = {
+		...manifest?.dependencies,
+		...manifest?.devDependencies
+	};
+	if (deps.next) return "nextjs";
+	if (deps.vite) return "vite";
+	return "unknown";
+}
+/**
+* A name Synq takes for an org, at most 100 characters: the package's, with
+* its scope as a prefix (`@rodai/website` is `rodai-website`, so the claim
+* page and the dashboard name the project someone knows), unless the name
+* starts with it already (`@acme/acme-web` is `acme-web`); else the folder's.
+*/
+function projectName(packageName, folder) {
+	const scoped = /^@([^/]+)\/(.*)$/s.exec(packageName?.trim() ?? "");
+	const [scope, rest] = scoped ? [scoped[1].trim(), scoped[2].trim()] : ["", packageName?.trim()];
+	return [...(scope && rest && rest !== scope && !rest.startsWith(`${scope}-`) ? `${scope}-${rest}` : rest) || folder].filter((char) => char.charCodeAt(0) >= 32 && char.charCodeAt(0) !== 127).join("").trim().slice(0, 100) || "my-app";
+}
+const MANAGERS = [
+	"pnpm",
+	"yarn",
+	"bun",
+	"npm"
+];
+/**
+* The package manager the project uses: from `dir` up to its git root, the
+* nearest folder that says, by its package.json's `packageManager`, a
+* lockfile or a pnpm workspace. An app inside a workspace (`apps/web`) has
+* no lockfile of its own: its workspace root's says, and `npm install` there
+* fails on `workspace:` dependencies. npm where nothing says.
+*/
+function packageManagerOf(dir) {
+	for (let at = dir;; at = dirname(at)) {
+		const named = /^(\w+)@/.exec(readManifest(at)?.packageManager ?? "")?.[1];
+		const declared = MANAGERS.find((manager) => manager === named);
+		if (declared) return declared;
+		if (existsSync(join(at, "pnpm-lock.yaml")) || existsSync(join(at, "pnpm-workspace.yaml"))) return "pnpm";
+		if (existsSync(join(at, "yarn.lock"))) return "yarn";
+		if (existsSync(join(at, "bun.lock")) || existsSync(join(at, "bun.lockb"))) return "bun";
+		if (existsSync(join(at, "package-lock.json"))) return "npm";
+		if (existsSync(join(at, ".git")) || dirname(at) === at) return "npm";
+	}
+}
+/** The port a dev script names (`--port 4000`, `-p 4000`), else the framework's. */
+function portOf(devScript, framework) {
+	const named = devScript && /(?:--port[ =]|-p\s+)(\d{1,5})\b/.exec(devScript);
+	const port = named ? Number(named[1]) : DEFAULT_PORTS[framework];
+	return port > 0 && port < 65536 ? port : DEFAULT_PORTS[framework];
+}
+/** The command that adds `packages` with this package manager. */
+function addCommand(manager, packages) {
+	switch (manager) {
+		case "pnpm": return [
+			"pnpm",
+			"add",
+			...packages
+		];
+		case "yarn": return [
+			"yarn",
+			"add",
+			...packages
+		];
+		case "bun": return [
+			"bun",
+			"add",
+			...packages
+		];
+		case "npm": return [
+			"npm",
+			"install",
+			...packages
+		];
+	}
+}
+/** The command that runs a package.json script. */
+function runCommand(manager, script) {
+	return manager === "npm" ? `npm run ${script}` : `${manager} ${script}`;
+}
+//#endregion
+//#region src/init.ts
+/** The CLI's own name, as npm and `npx` know it: one constant, so a rename is one line. */
+const CLI_NAME = "synqauth";
+/** The packages a Next.js app needs. */
+const NEXTJS_PACKAGES = ["@synqauth/nextjs"];
+/** Why init stopped before making anything, in words for the developer. */
+var InitError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.name = "InitError";
+		this.code = code;
+	}
+};
+async function init(options) {
+	for (const path of [
+		"package.json",
+		".env.local",
+		".gitignore"
+	]) checkFile(options.dir, path);
+	const project = readProject(options.dir);
+	const docs = originFor("synq", "docs", "production");
+	if (!project.manifest) throw new InitError(`There's no package.json in ${options.dir}. Run it in your app's folder.`, "no_project");
+	if (project.framework !== "nextjs") throw new InitError(`${CLI_NAME} init sets up Next.js apps. For ${project.framework === "vite" ? "a Vite app" : "this project"}, follow ${docs}/getting-started.`, "not_nextjs");
+	if (!project.appDir) throw new InitError(`${CLI_NAME} init sets up the App Router (an app/ or src/app/ folder), which this project doesn't have. Follow ${docs}/getting-started/nextjs.`, "no_app_router");
+	const appUrl = `https://localhost:${project.port}`;
+	const devCommand = runCommand(project.packageManager, "dev");
+	const planned = nextjsFiles(project.appDir, docs, {
+		appUrl,
+		command: devCommand
+	});
+	for (const path of [
+		".env.local",
+		".gitignore",
+		"package.json",
+		...planned.map((file) => file.path)
+	]) checkFile(project.dir, path);
+	const dev = project.manifest.scripts?.dev;
+	if (dev && !/\bnext\s+dev\b/.test(dev)) throw new InitError("Set scripts.dev to next dev before running init, so its HTTPS address matches the app.", "dev_script");
+	if (spawnSync("git", [
+		"ls-files",
+		"--error-unmatch",
+		"--",
+		".env.local"
+	], {
+		cwd: project.dir,
+		stdio: "ignore"
+	}).status === 0) throw new InitError("Stop tracking .env.local in git before running init; ignore rules cannot protect a tracked file.", "unsafe_file");
+	const envPath = join(project.dir, ".env.local");
+	const envText = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+	const present = synqNamesIn(envText);
+	if (present.length > 0 && !options.force) throw new InitError(`This project has Synq already: .env.local sets ${present.join(", ")}. Run ${CLI_NAME} init --force to make another development sign-in.`, "has_synq");
+	const made = await createClaimableOrg(apiOriginFor("synq", options.stage, options.env), {
+		name: project.name,
+		appType: "web",
+		redirectUris: [`${appUrl}/api/auth/callback`],
+		postLogoutRedirectUris: [appUrl]
+	}, {
+		fetch: options.fetch,
+		userAgent: `${CLI_NAME}/${options.version}`,
+		website: originFor("synq", "website", options.stage, options.env)
+	});
+	for (const path of [
+		".env.local",
+		".gitignore",
+		"package.json",
+		...planned.map((file) => file.path)
+	]) checkFile(project.dir, path);
+	if ((existsSync(envPath) ? readFileSync(envPath, "utf8") : "") !== envText) throw new InitError(".env.local changed during setup. Run init again after the other edit finishes.", "unsafe_file");
+	const date = new Date(made.claim.expires_at).toISOString().slice(0, 10);
+	const envBlock = withSynqBlock(envText, {
+		SYNQ_ISSUER: made.issuer,
+		SYNQ_CLIENT_ID: made.app.client_id,
+		SYNQ_CLIENT_SECRET: made.app.client_secret ?? "",
+		SYNQ_APP_URL: appUrl,
+		SYNQ_SESSION_SECRET: randomBytes(32).toString("base64"),
+		SYNQ_CLAIM_TOKEN: made.claim.token
+	}, [`Synq: a development sign-in from npx ${CLI_NAME} init, ${(options.now?.() ?? /* @__PURE__ */ new Date()).toISOString().slice(0, 10)}.`, `Claim it by ${date} or Synq deletes it: ${made.claim.url ?? "sign up, then claim it with SYNQ_CLAIM_TOKEN"}`]);
+	const fd = openSync(envPath, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW, 384);
+	try {
+		fchmodSync(fd, 384);
+		writeFileSync(fd, envBlock.slice(envText.length));
+	} finally {
+		closeSync(fd);
+	}
+	const written = [".env.local"];
+	const run = options.run ?? runIn;
+	const gitSays = await run([
+		"git",
+		"check-ignore",
+		"-q",
+		".env.local"
+	], project.dir, { quiet: true });
+	const gitignorePath = join(project.dir, ".gitignore");
+	const gitignore = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf8") : "";
+	const ignored = gitSays === 0 ? void 0 : gitSays === 1 ? withEnvLocalLine(gitignore) : withEnvLocalIgnored(gitignore);
+	if (ignored !== void 0) {
+		writeFileSync(gitignorePath, ignored);
+		written.push(".gitignore");
+	}
+	const kept = [];
+	for (const file of planned) {
+		const path = join(project.dir, file.path);
+		if (existsSync(path)) {
+			kept.push(file.path);
+			continue;
+		}
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, file.contents, { flag: "wx" });
+		written.push(file.path);
+	}
+	let devScript;
+	const https = dev ? httpsDevScript(dev) : "next dev --experimental-https";
+	if (https) {
+		const manifestPath = join(project.dir, "package.json");
+		const text = readFileSync(manifestPath, "utf8");
+		const indent = /^(\s+)"/m.exec(text)?.[1] ?? "  ";
+		const manifest = JSON.parse(text);
+		manifest.scripts ??= {};
+		manifest.scripts.dev = https;
+		writeFileSync(manifestPath, `${JSON.stringify(manifest, null, indent)}\n`);
+		devScript = {
+			from: dev ?? "(none)",
+			to: https
+		};
+		written.push("package.json");
+	}
+	let installed;
+	const deps = {
+		...project.manifest.dependencies,
+		...project.manifest.devDependencies
+	};
+	const missing = NEXTJS_PACKAGES.filter((name) => !deps[name]);
+	if (options.install && missing.length > 0) installed = await run(addCommand(project.packageManager, missing), project.dir) === 0;
+	return {
+		project,
+		made,
+		written,
+		kept,
+		devScript,
+		installed,
+		devCommand,
+		openUrl: `${appUrl}/synq`
+	};
+}
+/** Refuse symlinks, including parent folders, before making a remote org. */
+function checkFile(root, path) {
+	let cursor = join(root, path);
+	while (relative(root, cursor) !== "") {
+		let stat;
+		try {
+			stat = lstatSync(cursor);
+		} catch (error) {
+			if (!["ENOENT", "ENOTDIR"].includes(error.code ?? "")) throw error;
+		}
+		if (stat?.isSymbolicLink() || cursor === join(root, path) && stat && !stat.isFile()) throw new InitError(`Cannot set up ${path}: use ordinary files and folders, without symlinks.`, "unsafe_file");
+		cursor = dirname(cursor);
+	}
+}
+/**
+* Runs a command with the terminal's own input and output (none when quiet),
+* answering its exit code: 127, as a shell does, when it can't start.
+*/
+function runIn(command, cwd, { quiet = false } = {}) {
+	return new Promise((resolve) => {
+		const child = spawn(command[0], command.slice(1), {
+			cwd,
+			stdio: quiet ? "ignore" : "inherit",
+			shell: process.platform === "win32"
+		});
+		child.on("error", () => resolve(127));
+		child.on("exit", (code) => resolve(code ?? 1));
+	});
+}
+//#endregion
+//#region src/cli.ts
+const VERSION = "0.3.0";
+const HELP = `Usage: npx ${CLI_NAME} init [options]
+
+Gives your Next.js app a working Synq sign-in, with no account: a development
+sign-in you claim later by signing up.
+
+Options:
+  --force        Make another one even where .env.local has Synq's values
+  --no-install   Don't add @synqauth/nextjs with your package manager
+  --stage <s>    Which Synq: production (the default), preview, staging or local
+  -h, --help     Show this
+  -v, --version  Show the version`;
+const console_ = {
+	out: (line) => process.stdout.write(`${line}\n`),
+	err: (line) => process.stderr.write(`${line}\n`)
+};
+async function main(argv, context = {}) {
+	const output = context.output ?? console_;
+	let parsed;
+	try {
+		parsed = parse(argv);
+	} catch (error) {
+		output.err(error.message);
+		output.err(HELP);
+		return 2;
+	}
+	if (parsed.values.version) {
+		output.out(VERSION);
+		return 0;
+	}
+	const [command] = parsed.positionals;
+	if (parsed.values.help || command === void 0) {
+		output.out(HELP);
+		return command === void 0 && !parsed.values.help ? 2 : 0;
+	}
+	if (command !== "init" || parsed.positionals.length > 1) {
+		output.err(`${CLI_NAME} has no command "${command}".`);
+		output.err(HELP);
+		return 2;
+	}
+	const stage = parsed.values.stage;
+	if (!STAGES.includes(stage)) {
+		output.err(`--stage must be one of ${STAGES.join(", ")}.`);
+		return 2;
+	}
+	try {
+		const result = await init({
+			dir: context.cwd ?? process.cwd(),
+			stage,
+			env: context.env ?? process.env,
+			force: parsed.values.force === true,
+			install: parsed.values["no-install"] !== true,
+			version: VERSION,
+			fetch: context.fetch,
+			run: context.run
+		});
+		for (const line of summary(result)) output.out(line);
+		return result.installed === false ? 1 : 0;
+	} catch (error) {
+		if (error instanceof InitError || error instanceof SynqApiError) {
+			output.err(error.message);
+			return 1;
+		}
+		output.err("Setup could not finish. Check file permissions and your package manager. If .env.local was written, use its claim link; init keeps existing scaffold files.");
+		return 1;
+	}
+}
+function parse(argv) {
+	return parseArgs({
+		args: [...argv],
+		allowPositionals: true,
+		options: {
+			force: { type: "boolean" },
+			"no-install": { type: "boolean" },
+			stage: {
+				type: "string",
+				default: "production"
+			},
+			help: {
+				type: "boolean",
+				short: "h"
+			},
+			version: {
+				type: "boolean",
+				short: "v"
+			}
+		}
+	});
+}
+/** What init did, and what to do next, in the order a developer reads it. */
+function summary(result) {
+	const { made } = result;
+	const date = new Date(made.claim.expires_at).toISOString().slice(0, 10);
+	const lines = [
+		`Made a development sign-in for ${made.org.name}.`,
+		"",
+		...result.written.map((path) => `  wrote  ${path}`),
+		...result.kept.map((path) => `  kept   ${path} (yours already)`)
+	];
+	if (result.devScript) lines.push(`  dev    "${result.devScript.from}" now serves https: "${result.devScript.to}"`);
+	if (result.installed === false) lines.push("", "Adding @synqauth/nextjs failed: add it yourself before you start the app.");
+	lines.push("", "Next:", `  1. ${result.devCommand}`, "     Its first start may ask for your password, once, to trust a local certificate.", `  2. Open ${result.openUrl} and sign in.`, "     Sign-in needs the https address. If dev serves http instead, restart it in a", "     terminal and accept the prompt.", "", `Claim it by ${date} to keep it: sign up with this link and it's yours.`, `  ${made.claim.url ?? "Sign up, then claim it with SYNQ_CLAIM_TOKEN from .env.local."}`, `Until then it signs in up to ${made.limits.users} people, on localhost only.`);
+	return lines;
+}
+//#endregion
+export { init as a, InitError as i, summary as n, SynqApiError as o, CLI_NAME as r, main as t };

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+//#region src/api.d.ts
+type ClaimableOrg = {
+  org: {
+    id: string;
+    slug: string;
+    name: string;
+  };
+  issuer: string;
+  app: {
+    client_id: string;
+    client_secret: string | null;
+    redirect_uris: string[];
+  };
+  claim: {
+    token: string;
+    url: string | null;
+    expires_at: string;
+  };
+  limits: {
+    users: number;
+  };
+};
+/** Why Synq didn't make one, in words for the developer. */
+export declare class SynqApiError extends Error {
+  readonly code: string;
+  readonly status: number | undefined;
+  constructor(message: string, code: string, status?: number);
+}
+//#endregion
+//#region src/project.d.ts
+type Framework = 'nextjs' | 'vite' | 'unknown';
+type PackageManager = 'pnpm' | 'yarn' | 'bun' | 'npm';
+type Project = {
+  dir: string;
+  /** What the project is called: its package.json's name, its scope a prefix, else its folder's. */
+  name: string;
+  framework: Framework;
+  /** A Next.js App Router project's app folder, relative to `dir`: `app` or `src/app`. */
+  appDir?: string;
+  packageManager: PackageManager;
+  /** Where its dev server listens: Next.js's 3000 and Vite's 5173 unless its dev script says. */
+  port: number;
+  /** Its package.json, as read. */
+  manifest: PackageManifest | undefined;
+};
+type PackageManifest = {
+  name?: string;
+  /** Corepack's field: `pnpm@10.0.0`, say. */
+  packageManager?: string;
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+};
+//#endregion
+//#region src/init.d.ts
+/** The CLI's own name, as npm and `npx` know it: one constant, so a rename is one line. */
+export declare const CLI_NAME = "synqauth";
+/** Which Synq: production for everyone, the others for people working on Synq. */
+type Stage = 'production' | 'preview' | 'staging' | 'local';
+type InitOptions = {
+  dir: string;
+  /** Which Synq to use: production unless a developer of Synq says otherwise. */
+  stage: Stage;
+  /** For `local`: where the local stack's API is (`SYNQ_API_URL`), and the website's. */
+  env: Record<string, string | undefined>;
+  /** Make one even where .env.local has Synq's values already (they're appended again). */
+  force: boolean;
+  /** Add @synqauth/nextjs with the project's package manager. */
+  install: boolean;
+  version: string;
+  fetch?: typeof fetch;
+  /**
+   * Runs a command in the project, answering its exit code (127 when it
+   * can't start): an install, git's view of `.env.local`, in tests a fake.
+   * `quiet` runs it without the terminal's input and output.
+   */
+  run?: (command: readonly string[], cwd: string, options?: {
+    quiet?: boolean;
+  }) => Promise<number>;
+  now?: () => Date;
+};
+type InitResult = {
+  project: Project;
+  made: ClaimableOrg;
+  /** Files written, relative to the project. */
+  written: string[];
+  /** Files left as they were because the project has them. */
+  kept: string[];
+  /** What changed in package.json's dev script, if anything. */
+  devScript?: {
+    from: string;
+    to: string;
+  };
+  /** Whether @synqauth/nextjs was added: true, false when it failed, undefined when not tried. */
+  installed?: boolean;
+  /** How to start the dev server, and the page to open. */
+  devCommand: string;
+  openUrl: string;
+};
+/** Why init stopped before making anything, in words for the developer. */
+export declare class InitError extends Error {
+  readonly code: 'no_project' | 'not_nextjs' | 'no_app_router' | 'has_synq' | 'unsafe_file' | 'dev_script';
+  constructor(message: string, code: InitError['code']);
+}
+export declare function init(options: InitOptions): Promise<InitResult>;
+//#endregion
+//#region src/cli.d.ts
+type Output = {
+  out: (line: string) => void;
+  err: (line: string) => void;
+};
+export declare function main(argv: readonly string[], context?: {
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  output?: Output;
+  run?: Parameters<typeof init>[0]['run'];
+  fetch?: typeof fetch;
+}): Promise<number>;
+/** What init did, and what to do next, in the order a developer reads it. */
+export declare function summary(result: InitResult): string[];
+//#endregion
+export type { InitOptions, InitResult, Stage };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as init, i as InitError, n as summary, o as SynqApiError, r as CLI_NAME, t as main } from "./cli-C7dDFb81.js";
+export { CLI_NAME, InitError, SynqApiError, init, main, summary };

package/package.json

@@ -1,11 +1,43 @@
 {
   "name": "synqauth",
-  "version": "0.0.0",
-  "description": "Synq's CLI: npx synqauth init gives your app a working sign-in. This placeholder holds the name until the first release.",
+  "version": "0.3.0",
+  "description": "Synq's command line: npx synqauth init gives your Next.js app a working sign-in, with no account until you claim it.",
   "license": "MIT",
-  "homepage": "https://synq.build",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/aerosol-build/synq.git"
+    "url": "git+https://github.com/aerosol-build/synq.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "synqauth": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@synq/links": "0.0.0",
+    "@vitest/coverage-v8": "5.0.2",
+    "vitest": "5.0.2"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc",
+    "test": "vitest run --coverage"
   }
-}
+}