@elixpo/lixblogs-cli 1.1.2

package/API.md

@@ -0,0 +1,86 @@
+# LixBlogs API v1 contract
+
+The CLI is a public OAuth client. Accounts issues credentials; LixBlogs is the
+resource server. The CLI must never connect to D1 or carry a client secret.
+
+## Origins and discovery
+
+- OAuth issuer: `https://accounts.elixpo.com`
+- Token audience: `blogs.elixpo.com`
+- Resource root: `https://blogs.elixpo.com/api/v1`
+- Contract metadata: `GET /api/v1`
+
+Production bearer tokens are EdDSA access tokens issued to an allowlisted CLI
+client. LixBlogs verifies their signature, expiry, audience, client, scopes,
+and local account before querying creator data. Tokens are never persisted or
+logged by the resource API.
+
+## Initial resources
+
+| Method | Path | Scope | Behavior |
+| --- | --- | --- | --- |
+| `GET` | `/api/v1` | public | API and compatibility metadata |
+| `GET` | `/api/v1/blogs` | `lixblogs:blog:read` | Accessible blog metadata |
+| `GET` | `/api/v1/blogs/{id}` | `lixblogs:blog:read` | One accessible blog and its content |
+| `POST` | `/api/v1/blogs` | `lixblogs:blog:write` | Create a draft |
+| `PATCH` | `/api/v1/blogs/{id}` | `lixblogs:blog:write` | Edit a draft or post |
+| `POST` | `/api/v1/blogs/{id}/publish` | `lixblogs:blog:publish` | Publish a post |
+| `POST` | `/api/v1/blogs/{id}/unpublish` | `lixblogs:blog:publish` | Return a post to draft |
+| `DELETE` | `/api/v1/blogs/{id}` | `lixblogs:blog:delete` | Move a post to trash |
+| `POST` | `/api/v1/blogs/{id}/restore` | `lixblogs:blog:delete` | Restore a trashed post |
+
+`GET /api/v1/blogs` accepts `status=all|draft|published`, `limit=1..100`, and
+an opaque `cursor`. Results include authored blogs, accepted collaborations,
+and blogs belonging to organizations of which the caller is a member. Access
+misses return `404` so resource existence is not disclosed.
+
+Permanent deletion uses `DELETE /api/v1/blogs/{id}?permanent=true`. It requires
+the additional `lixblogs:blog:delete:permanent` scope and an
+`X-Confirm-Permanent-Delete` header equal to the blog ID.
+
+## Response shape
+
+Successful responses use:
+
+```json
+{ "data": {}, "meta": {} }
+```
+
+Errors use a stable machine-readable envelope:
+
+```json
+{
+  "error": {
+    "code": "invalid_token",
+    "message": "The access token is malformed.",
+    "requestId": "..."
+  }
+}
+```
+
+Every response carries `X-LixBlogs-API-Version` and `X-Request-ID`. Authenticated
+responses also expose bounded per-minute `X-RateLimit-*` values. Clients should
+use error codes rather than matching human-readable messages.
+
+## Concurrency and retries
+
+Single-blog reads include a strong `ETag`. Future write endpoints require
+`If-Match` so a stale CLI cannot silently overwrite a newer browser edit.
+
+Mutation requests use an `Idempotency-Key` containing 8–128 URL-safe
+characters. Reservations live for 24 hours:
+
+- same key and same request: replay the retained response;
+- same key while running: `idempotency_in_progress`;
+- same key with different input: `idempotency_key_reused`.
+
+Operational rows are pruned in bounded batches. Audit events record the caller,
+client, action, resource, outcome, and request ID, never bearer material.
+
+## Compatibility policy
+
+The `/api/v1` URL and envelope are stable for the v1 lifetime. Fields may be
+added without a major version change; existing fields and error codes are not
+removed or redefined. A breaking change requires `/api/v2`. The metadata
+endpoint advertises `minCliVersion`; clients below it must stop before making
+authenticated requests and present an upgrade instruction.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elixpo (Ayushman Bhattacharya)
+
+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

@@ -0,0 +1,157 @@
+# @elixpo/lixblogs-cli
+
+The official CLI for LixBlogs — publish, manage, and inspect blogs through
+the supported API. Built for creators and agent/automation use.
+
+**Status: initial release.** This package implements production device-flow
+authentication and the core blog lifecycle over the stable LixBlogs API v1
+contract. The interactive terminal UI is intentionally a separate follow-up.
+
+## Install (local development)
+
+```bash
+cd packages/lixblogs-cli
+npm install
+```
+
+There's no published npm release yet. Once available, install will be:
+```bash
+npm install -g @elixpo/lixblogs-cli
+```
+
+## Usage
+
+```bash
+node bin/lixblogs.mjs --help
+```
+
+### Authentication
+
+```bash
+# Log in via device authorization
+node bin/lixblogs.mjs auth login
+
+# Check login status
+node bin/lixblogs.mjs auth status
+
+# List profiles and choose the active one
+node bin/lixblogs.mjs auth profiles
+node bin/lixblogs.mjs auth use work
+
+# Log out (clears local credentials only)
+node bin/lixblogs.mjs auth logout
+
+# Revoke the token server-side and clear local credentials (destructive)
+node bin/lixblogs.mjs auth revoke --yes
+```
+
+### Blog lifecycle
+
+Request the permissions needed for the operations you intend to use:
+
+```bash
+node bin/lixblogs.mjs auth login \
+  --scope openid --scope profile --scope lixblogs:blog:read \
+  --scope lixblogs:blog:write --scope lixblogs:blog:publish \
+  --scope lixblogs:blog:delete
+```
+
+Then work with Markdown without any database or Cloudflare credentials:
+
+```bash
+lixblogs blog list --status draft
+lixblogs blog create --file post.md --title "A new post" --tag engineering
+lixblogs blog get <id> --json
+lixblogs blog edit <id> --editor
+lixblogs blog publish <id>
+lixblogs blog unpublish <id>
+lixblogs blog delete <id> --yes
+lixblogs blog list --status trashed
+lixblogs blog restore <id>
+```
+
+`create`, `edit`, `publish`, `unpublish`, `delete`, and `restore` accept
+`--dry-run`. Content input is mutually exclusive: `--file`, `--stdin`,
+`--content`, or `--editor`. Permanent deletion additionally requires
+`--permanent --yes` and the `lixblogs:blog:delete:permanent` scope.
+
+Edits use the server ETag automatically. If another editor wins the race, the
+command exits with code 3 and retains both versions under
+`.lixblogs-conflicts/`; it never overwrites the newer server revision.
+
+Global flags:
+- `--profile <name>` — named profile to use (default: `"default"`)
+- `--env <environment>` — override environment (`development` | `staging` | `production`)
+- `--scope <scope>` — request an additional/alternate OAuth scope; repeatable
+- `--open` — open the verification URL with the device code pre-filled
+- `--accounts-url <url>` — override the Accounts issuer for local/staging tests
+- `--api-url <url>` — override the LixBlogs API origin; production defaults to
+  `https://blogs.elixpo.com`
+- `--json` — machine-readable JSON output
+- `--quiet` — suppress non-essential output
+- `--yes`, `-y` — auto-confirm destructive actions (required for `revoke`)
+- `--allow-insecure-fallback` — explicit opt-in: if the OS keychain is
+  unavailable, use a non-persistent in-memory store instead of failing
+
+### Service boundary
+
+- `https://accounts.elixpo.com` issues, refreshes, and revokes OAuth tokens.
+- `https://blogs.elixpo.com/api/v1` is the only production resource API.
+- The CLI discovers Accounts endpoints before login and rejects incompatible
+  contract versions or endpoints on an unexpected origin.
+- The mock provider is available only with an explicit non-production
+  environment, for example `--env development --auth-provider mock`.
+- The resource contract, scopes, pagination, errors, and mutation guarantees
+  are documented in [API.md](API.md).
+
+The production client is public and has no client secret. Never add one to
+CLI configuration, package files, or GitHub secrets.
+
+## Development
+
+```bash
+npm test          # runs the full CLI test suite
+```
+
+Tests exercise both a mocked auth provider and, where relevant, the real
+OS keychain backend on whatever machine runs them — see
+`THREAT_MODEL.md` and inline comments in `src/config/KeychainCredentialStore.js`
+for known platform-specific behavior (e.g. a documented WSL/keyring-rs quirk).
+
+## Architecture
+
+```
+bin/lixblogs.mjs         CLI entry point (Node's native util.parseArgs, no
+                         third-party parsing dependency)
+src/auth/                Accounts provider, development mock, refresh-safe
+                         authenticated client, and production safety gate
+src/commands/auth/       Command logic (login, status, logout, revoke) —
+                         framework-agnostic, testable independently of the CLI shell
+src/commands/blog/       Blog lifecycle commands and Markdown/editor input
+src/api/                 Versioned LixBlogs resource client and stable errors
+src/content/             Dependency-free Markdown/block conversion
+src/config/              Credential storage (real keychain + gated fallback),
+                         profile registry, config resolution, token redaction
+tests/                   Full test suite
+THREAT_MODEL.md          Security threat model for the auth system
+```
+
+Command logic under `src/commands/` is deliberately decoupled from the CLI
+parsing layer in `bin/`, so the parser (or any other interface built on top
+of these commands later) can change without touching command logic or its
+tests.
+
+## Roadmap
+
+See [#135](https://github.com/elixpo/blogs.elixpo/issues/135) for the full
+scope. Rough remaining order:
+
+1. Media, organization, and stats commands
+2. Packaging and release automation
+3. Interactive terminal UI and branding in a separate issue
+4. Agent skill packages and cross-repository E2E coverage
+
+## Contributing
+
+This package is part of the [blogs.elixpo](https://github.com/elixpo/blogs.elixpo)
+monorepo. See the root repository's contribution guidelines.

package/THREAT_MODEL.md

@@ -0,0 +1,91 @@
+# LixBlogs CLI — Auth Threat Model
+
+Tracking: elixpo/blogs.elixpo#137
+Status: **Resolved by implementer** — this doc's existence and scope was an
+open question on #137 ("should a threat model be written as part of this
+issue, and what should it contain?"). Decision: yes, scoped to the five
+areas #137 itself named. Flagged for the maintainer to expand or narrow.
+
+## 1. Token storage
+
+- Access and refresh tokens are stored in the OS keychain
+  (Keychain on macOS, Secret Service/libsecret on Linux, Credential Manager
+  on Windows) — never in a plain config file or environment variable by
+  default.
+- A fallback (e.g. encrypted file on disk) is only used if the keychain is
+  unavailable, and only with explicit user opt-in at that moment — never a
+  silent default.
+- Redaction: tokens must never appear in logs, `--json` output, telemetry,
+  or crash reports. This is verified by test (see `auth.test.mjs`), not
+  just documented — string values matching known token prefixes should be
+  masked in any error-serialization path.
+- Risk if this fails: a leaked token grants whatever scopes it holds until
+  revoked or expired — this is why short-lived access tokens (with refresh
+  rotation) matter more than keychain storage alone.
+
+## 2. Scope boundaries
+
+- Scopes are least-privilege by default; publishing and destructive actions
+  require scopes distinct from read/draft scopes (per #135).
+- Accounts publishes the registered LixBlogs scope list. Login defaults to
+  identity plus profile/blog read scopes; broader scopes must be requested
+  explicitly and remain bounded by the public client's registration.
+- Risk: an overly broad default scope grant (e.g. `login` implicitly
+  granting `publish`) would mean any compromised session can publish
+  without the user having explicitly consented to that. Mitigation: the
+  CLI must request only the scopes a given command needs, not a blanket
+  "everything" scope at login time.
+
+## 3. Blast radius of a compromised agent/CLI session
+
+- Worst case if a token is stolen or an agent is compromised: whatever
+  scopes that specific token holds, until it's revoked or naturally
+  expires (access tokens are short-lived; refresh tokens are the more
+  valuable target).
+- Mitigations already in scope: `lixblogs auth revoke`, tested refresh
+  rotation/reuse rejection, and multi-profile isolation (below).
+- Not yet mitigated / open for later work: there's no mechanism yet for a
+  user to see "which sessions/devices currently hold a valid token for my
+  account" and revoke just one — this would materially reduce blast radius
+  and is worth a follow-up issue, not blocking this one.
+
+## 4. Device-flow-specific risks
+
+- **Code interception**: the user code is short and meant to be read aloud/
+  typed manually; the device code (long, unguessable) is what's actually
+  exchanged for a token. If a device code leaks (e.g. via a compromised
+  clipboard), same blast radius as a stolen token.
+- **Polling abuse**: a malicious client could poll rapidly to try to beat
+  the user to approving/denying. Mitigated by `pollIntervalSeconds` and the
+  `slow_down` response (see MockAuthProvider) which forces callers to back
+  off — the real provider is expected to enforce this server-side too, not
+  just suggest it.
+- **Expired/denied code handling**: both must be treated as fully dead ends
+  — no retry-with-same-code path. The mock encodes this by design (an
+  expired/denied device code never later returns `approved`).
+- **Reused-code replay**: an already-approved device code should not be
+  usable to fetch a second, independent token. Not yet tested in the mock
+  — worth adding once the "one device code → one token exchange" contract
+  is confirmed for the real provider, since the mock doesn't currently
+  invalidate a code after issuing a token for it.
+
+## 5. Multi-profile / account isolation
+
+- Each named profile's tokens must be stored under a distinct keychain
+  entry — one profile's credential lookup must never return another
+  profile's token, even if both are logged in simultaneously.
+- Switching the active profile must not require re-entering credentials for
+  profiles already logged in, but must also never leak which other profiles
+  exist to a scope that shouldn't know (e.g. `--json` output for one
+  profile shouldn't enumerate other profiles' identifiers).
+- The active profile is non-sensitive registry metadata. Each profile's
+  credentials remain isolated in its own OS-keychain entry, and concurrent
+  refreshes for one profile share a single rotation operation.
+
+## Explicitly out of scope for this document
+
+- Threat modeling the API server itself (auth middleware, D1 access
+  patterns) — that's elixpo/blogs.elixpo#136's concern.
+- Supply-chain risk on the npm package itself (dependency compromise,
+  publish-time integrity) — worth a separate doc once packaging/release
+  work (later phase) is underway.