@gjsify/system-accounts 0.0.0-stage → 0.55.0

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# @gjsify/system-accounts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The accounts a user already set up on their system: find them, read their mail server settings, log in without asking for a password again. The interface is the capabilities a caller needs; a driver per platform maps the system's account store onto them ([ADR 0095](../../../docs/adr/0095-system-accounts-are-asked-by-capability.md)).
+
+Part of the [gjsify](https://github.com/gjsify/gjsify) project. **Tier 3 (experimental, ADR 0003)**: new, one driver, no promise yet.
+
+## Installation
+
+```bash
+gjsify install @gjsify/system-accounts
+```
+
+## Usage
+
+```typescript
+import { createSystemAccounts, isUnavailable } from '@gjsify/system-accounts';
+
+const accounts = createSystemAccounts();
+if (accounts.capabilities().services.length === 0) {
+    // No account store on this host: ask the user instead.
+}
+
+for (const account of await accounts.listAccounts('mail')) {
+    const mail = await accounts.getMailSettings(account);
+    if (isUnavailable(mail) || !mail.smtp) continue;
+
+    const credentials = await accounts.getCredentials(account, 'smtp');
+    if (credentials.kind === 'password') login(mail.smtp, credentials.secret);
+    if (credentials.kind === 'oauth2') loginXoauth2(mail.smtp, credentials.token); // valid until credentials.expiresAt
+}
+```
+
+| Call | Answers |
+|---|---|
+| `capabilities()` | what THIS host can answer: `services` it lists, `credentials` kinds it hands out. Both empty without an account store |
+| `listAccounts(service?)` | `Account[]` (id, provider, identity, label, enabled services). Empty when the store cannot be reached |
+| `getMailSettings(account)` | `{ sender, imap?, smtp? }`, each server as host, port, `security` (`tls` / `starttls` / `none`) and user name; or `Unavailable` |
+| `getCredentials(account, purpose)` | `{ kind: 'password', secret }`, `{ kind: 'oauth2', token, expiresAt }`, or `Unavailable` |
+
+**A missing capability is a value, never an exception.** `Unavailable` carries a `reason`: `no-account-store`, `unknown-account`, `not-supported` (the account has no mail server, no credentials) or `credentials-unavailable` (the store would not hand the secret out). The ADR's `Credentials` has two members; the third is how that rule is spelled for a call that has to return one.
+
+**Secrets** go to the caller and nowhere else: never logged, cached or put in an error. They are read per call; an OAuth2 token carries its expiry, so ask again afterwards instead of keeping it.
+
+## Platforms
+
+| Platform | State |
+|---|---|
+| Linux, GNOME | **driver**: GNOME Online Accounts through `libgoa` (`gi://Goa?version=1.0&optional`). A host without the typelib still starts and reports empty capabilities |
+| Linux without GOA, macOS, Windows | no driver; empty capabilities. Whether a platform offers a usable account store to third-party apps is **unexplored**, not ruled out |
+| Android, iOS, browser | not served (`gjsify.runtimes`: only `gjs` is `native`) |
+
+IMAP and SMTP passwords are looked up under the ids GOA keeps them under (`imap-password`, `smtp-password`); SMTP falls back to the stored IMAP password, because one login often serves both.
+
+## Testing
+
+`libgoa` has no constructor that takes a connection: `Goa.Client.new` dials the session bus. `src/fake-goa.ts` therefore exports the interfaces it calls (`ObjectManager`, `PasswordBased`, `OAuth2Based`, and the few bus methods a client needs) on a peer-to-peer `Gio.DBusServer` and points the session address at it, so the driver runs libgoa's own client code with no GNOME session, no real account and no keyring. Dummy secrets are compared, never printed.
+
+- GLib caches the session connection per process. Run the suite through `test:gjs`, which starts it with a dead bus path; the fake refuses to go on if the process is already bound to a real bus, so a developer's accounts never reach a test.
+- The mapping from account fields to the contract (host/port splitting, `tls`/`starttls`/`none` from the two flags and the port, which password ids to try) is pure and runs on Node too.
+- Not covered: a real session bus, a real provider (the OAuth2 path has run against the fake only), and a host whose `libgoa` is genuinely missing (the empty-capabilities path is tested by passing no namespace).
+- The `&optional` import costs a top-level await in the bundle that reaches it, and a `@gjsify/unit` run wedges on it (ADR 0085 clause 5). The specs therefore reach the driver (`src/goa.ts`) directly; only `createSystemAccounts` (`src/system-accounts.ts`) carries the flag.
+
+## License
+
+MIT

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/goa.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{enabledServices as e,mailSettingsFrom as t,passwordIds as n}from"./mapping.js";import{isUnavailable as r,noAccountStore as i}from"./no-account-store.js";import a from"gi://GLib?version=2.0";import o from"gi://Gio?version=2.0";const unavailable=e=>({kind:`unavailable`,reason:e});function newClient(e,t){return new Promise((n,r)=>{e.Client.new(t,(t,i)=>{try{n(e.Client.new_finish(i))}catch(e){r(e)}})})}async function connect(e,t){let n=new o.Cancellable,r=a.timeout_add(a.PRIORITY_DEFAULT,t,()=>(n.cancel(),a.SOURCE_REMOVE));try{return await newClient(e,n)}catch{return}finally{a.Source.remove(r)}}function secretOf(e,t){return new Promise(n=>{e.call_get_password(t,null,(t,r)=>{try{let[t,i]=e.call_get_password_finish(r);n(t&&i?i:void 0)}catch{n(void 0)}})})}function tokenOf(e){return new Promise(t=>{e.call_get_access_token(null,(n,r)=>{try{let[n,i,a]=e.call_get_access_token_finish(r);t(n&&i?[i,a]:void 0)}catch{t(void 0)}})})}function toAccount(t){let n=t.get_account();if(n)return{id:n.id??``,provider:n.provider_type??``,providerName:n.provider_name??``,identity:n.identity??``,label:n.presentation_identity??``,services:e({mail:!!t.get_mail(),calendar:!!t.get_calendar(),contacts:!!t.get_contacts(),files:!!t.get_files()},{mail:!!n.mail_disabled,calendar:!!n.calendar_disabled,contacts:!!n.contacts_disabled,files:!!n.files_disabled})}}function createGoaAccounts({goa:e,now:a=Date.now,connectTimeoutMs:o=5e3}){if(!e)return i;let s,client=async()=>{s??=connect(e,o);let t=await s;return t||(s=void 0),t};async function find(e){let t=await client();return t?t.lookup_by_id(e.id)??unavailable(`unknown-account`):unavailable(`no-account-store`)}return{capabilities:()=>({services:[`mail`,`calendar`,`contacts`,`files`],credentials:[`password`,`oauth2`]}),async listAccounts(e){let t=await client();if(!t)return[];let n=t.get_accounts().flatMap(e=>toAccount(e)??[]);return e?n.filter(t=>t.services.includes(e)):n},async getMailSettings(e){let n=await find(e);if(r(n))return n;let i=n.get_mail();return i?t({emailAddress:i.email_address??``,name:i.name??``,imapSupported:i.imap_supported,imap:{host:i.imap_host??``,userName:i.imap_user_name??``,useSsl:i.imap_use_ssl,useTls:i.imap_use_tls},smtpSupported:i.smtp_supported,smtp:{host:i.smtp_host??``,userName:i.smtp_user_name??``,useSsl:i.smtp_use_ssl,useTls:i.smtp_use_tls,authenticate:i.smtp_use_auth}})??unavailable(`not-supported`):unavailable(`not-supported`)},async getCredentials(e,t){let i=await find(e);if(r(i))return i;let o=i.get_oauth2_based();if(o){let e=await tokenOf(o);if(!e)return unavailable(`credentials-unavailable`);let[t,n]=e;return{kind:`oauth2`,token:t,expiresAt:a()+n*1e3}}let s=i.get_password_based();if(!s)return unavailable(`not-supported`);for(let e of n(t)){let t=await secretOf(s,e);if(t!==void 0)return{kind:`password`,secret:t}}return unavailable(`credentials-unavailable`)}}}export{createGoaAccounts};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import{isUnavailable as e}from"./no-account-store.js";import{createSystemAccounts as t}from"./system-accounts.js";export{t as createSystemAccounts,e as isUnavailable};

package/lib/esm/mapping.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";function splitHostPort(e){let t=e.trim(),n=/^\[([^\]]+)\](?::(\d*))?$/.exec(t);if(n)return{host:n[1],port:parsePort(n[2])};let r=t.indexOf(`:`);return r===-1||r!==t.lastIndexOf(`:`)?{host:t}:{host:t.slice(0,r),port:parsePort(t.slice(r+1))}}function parsePort(e){if(!e||!/^\d+$/.test(e))return;let t=Number.parseInt(e,10);return t>=1&&t<=65535?t:void 0}const e={imap:993,smtp:465},t={imap:{tls:993,starttls:143,none:143},smtp:{tls:465,starttls:587,none:25}};function securityFromFlags(t,n,r,i){return n?`tls`:r?`starttls`:i===e[t]?`tls`:`none`}function serverSettingsFrom(e,n){let{host:r,port:i}=splitHostPort(n.host);if(!r)return;let a=securityFromFlags(e,n.useSsl,n.useTls,i);return{host:r,port:i??t[e][a],security:a,...n.authenticate&&n.userName?{username:n.userName}:{}}}function mailSettingsFrom(e){let t=e.imapSupported?serverSettingsFrom(`imap`,{...e.imap,authenticate:!0}):void 0,n=e.smtpSupported?serverSettingsFrom(`smtp`,e.smtp):void 0;if(!(!t&&!n))return{sender:{address:e.emailAddress,...e.name?{name:e.name}:{}},...t?{imap:t}:{},...n?{smtp:n}:{}}}function enabledServices(e,t){return[`mail`,`calendar`,`contacts`,`files`].filter(n=>e[n]&&!t[n])}function passwordIds(e){return e===`imap`?[`imap-password`,`password`,``]:[`smtp-password`,`imap-password`,`password`,``]}export{enabledServices,mailSettingsFrom,passwordIds,securityFromFlags,serverSettingsFrom,splitHostPort};

package/lib/esm/no-account-store.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";const e={kind:`unavailable`,reason:`no-account-store`},t={capabilities:()=>({services:[],credentials:[]}),listAccounts:async()=>[],getMailSettings:async()=>e,getCredentials:async()=>e};function isUnavailable(e){return`kind`in e&&e.kind===`unavailable`}export{isUnavailable,t as noAccountStore};

package/lib/esm/system-accounts.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{createGoaAccounts as e}from"./goa.js";import t from"gi://Goa?version=1.0&optional";function createSystemAccounts(){return e({goa:t})}export{createSystemAccounts};

package/lib/types/fake-goa.d.ts

@@ -0,0 +1,43 @@
+import type { AccountService } from './types.js';
+export interface FakeMail {
+    readonly email: string;
+    readonly name: string;
+    readonly imap?: {
+        host: string;
+        user: string;
+        ssl: boolean;
+        tls: boolean;
+    };
+    readonly smtp?: {
+        host: string;
+        user: string;
+        ssl: boolean;
+        tls: boolean;
+        auth: boolean;
+    };
+}
+export interface FakeAccount {
+    readonly id: string;
+    readonly provider?: string;
+    readonly identity?: string;
+    readonly disabled?: Partial<Record<AccountService, boolean>>;
+    readonly mail?: FakeMail;
+    readonly calendar?: boolean;
+    readonly contacts?: boolean;
+    readonly files?: boolean;
+    /** Secret id → dummy secret. */
+    readonly passwords?: Readonly<Record<string, string>>;
+    readonly oauth2?: {
+        readonly token: string;
+        readonly expiresIn: number;
+    };
+}
+export interface FakeGoa {
+    setAccounts(accounts: readonly FakeAccount[]): void;
+    /** The secret ids libgoa was asked for since `setAccounts`, never the secrets. */
+    readonly requestedPasswordIds: string[];
+    /** How many `GetManagedObjects` calls arrived: proof the driver talked to THIS server. */
+    managedObjectsCalls(): number;
+}
+/** One fake per process; later calls return the same one, so a test sets its own accounts. */
+export declare function startFakeGoa(): Promise<FakeGoa>;

package/lib/types/goa.d.ts

@@ -0,0 +1,9 @@
+import type Goa from 'gi://Goa?version=1.0';
+import type { SystemAccounts } from './types.js';
+export interface GoaOptions {
+    /** The libgoa namespace, or `undefined` on a host without it. */
+    readonly goa: typeof Goa | undefined;
+    readonly now?: () => number;
+    readonly connectTimeoutMs?: number;
+}
+export declare function createGoaAccounts({ goa, now, connectTimeoutMs, }: GoaOptions): SystemAccounts;

package/lib/types/goa.gjs.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/system-accounts.d.ts

@@ -0,0 +1,3 @@
+import type { SystemAccounts } from './types.js';
+/** The Linux driver on the host's libgoa, or the no-store answer when the host has none. */
+export declare function createSystemAccounts(): SystemAccounts;

package/package.json

@@ -1,6 +1,89 @@
 {
-  "name": "@gjsify/system-accounts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@gjsify/system-accounts",
+    "version": "0.55.0",
+    "description": "The accounts a user already set up on their system: find them, read their mail server settings, get credentials. GNOME Online Accounts on Linux.",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "type": "module",
+    "sideEffects": false,
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        }
+    },
+    "files": [
+        "lib",
+        "!lib/types/fake-goa.d.ts",
+        "!lib/types/**/*.spec.d.ts"
+    ],
+    "scripts": {
+        "clear": "gjsify clear lib tmp tsconfig.tsbuildinfo test.gjs.mjs test.node.mjs",
+        "check": "gjsify tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}' 'src/test.gjs.mts' 'src/fake-goa.ts'",
+        "build:types": "gjsify tsc",
+        "build:test": "gjsify run build:test:gjs && gjsify run build:test:node",
+        "build:test:gjs": "gjsify build src/test.gjs.mts --app gjs --outfile test.gjs.mjs",
+        "build:test:node": "gjsify build src/test.mts --app node --outfile test.node.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:node && gjsify run test:gjs",
+        "test:gjs": "gjsify env DBUS_SESSION_BUS_ADDRESS=unix:path=/nonexistent XDG_RUNTIME_DIR=/nonexistent gjsify run test.gjs.mjs",
+        "test:node": "node test.node.mjs"
+    },
+    "keywords": [
+        "gjs",
+        "accounts",
+        "gnome-online-accounts",
+        "goa",
+        "mail",
+        "imap",
+        "smtp"
+    ],
+    "dependencies": {
+        "@girs/gio-2.0": "5.4.0",
+        "@girs/gjs": "5.4.0",
+        "@girs/glib-2.0": "5.4.0",
+        "@girs/gobject-2.0": "5.4.0",
+        "@girs/goa-1.0": "5.4.0"
+    },
+    "devDependencies": {
+        "@gjsify/cli": "^0.55.0",
+        "@gjsify/unit": "^0.55.0",
+        "typescript": "^6.0.3"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/gjs/system-accounts"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/gjs/system-accounts#readme",
+    "gjsify": {
+        "tier": 3,
+        "runtimes": {
+            "gjs": "native",
+            "node": "none",
+            "browser": "none",
+            "nativescript": "none"
+        },
+        "headless": [
+            "Gdk",
+            "GdkPixbuf",
+            "Gsk",
+            "Gtk",
+            "Adw"
+        ],
+        "os": {
+            "linux": "supported",
+            "darwin": "none",
+            "win32": "none"
+        },
+        "osNotes": {
+            "darwin": "No driver: the package answers with empty capabilities (ADR 0095). macOS has no system-account API for third-party apps that was found; this is not proven either way.",
+            "win32": "No driver: the package answers with empty capabilities (ADR 0095). No system-account API for third-party apps was found; this is not proven either way."
+        }
+    }
+}