@gjsify/system-accounts 0.0.0-stage → 0.56.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/index.d.ts

@@ -0,0 +1,3 @@
+export { createSystemAccounts } from './system-accounts.js';
+export { isUnavailable } from './no-account-store.js';
+export type { Account, AccountCapabilities, AccountService, ConnectionSecurity, CredentialKind, CredentialPurpose, Credentials, MailSettings, OAuth2Credentials, PasswordCredentials, ServerSettings, SystemAccounts, Unavailable, UnavailableReason, } from './types.js';

package/lib/types/mapping.d.ts

@@ -0,0 +1,44 @@
+import type { AccountService, ConnectionSecurity, CredentialPurpose, MailSettings, ServerSettings } from './types.js';
+export interface HostPort {
+    readonly host: string;
+    readonly port?: number;
+}
+/**
+ * Split `host`, `host:port` and `[v6]:port`. A bare IPv6 literal has several colons and no
+ * port. A port outside 1..65535 is dropped rather than guessed, so the caller falls back to
+ * the protocol default instead of dialling port 0.
+ */
+export declare function splitHostPort(raw: string): HostPort;
+/**
+ * The two flags an account store keeps for transport security. When neither is set the
+ * port still tells: 993/465 is TLS from the first byte, which some stores leave unflagged.
+ */
+export declare function securityFromFlags(protocol: CredentialPurpose, useSsl: boolean, useTls: boolean, explicitPort?: number): ConnectionSecurity;
+export interface ServerFields {
+    readonly host: string;
+    readonly userName: string;
+    readonly useSsl: boolean;
+    readonly useTls: boolean;
+    /** False for a server that takes no login: the user name is then not reported. */
+    readonly authenticate: boolean;
+}
+/** `undefined` when the account names no host. */
+export declare function serverSettingsFrom(protocol: CredentialPurpose, fields: ServerFields): ServerSettings | undefined;
+export interface MailFields {
+    readonly emailAddress: string;
+    readonly name: string;
+    readonly imapSupported: boolean;
+    readonly imap: Omit<ServerFields, 'authenticate'>;
+    readonly smtpSupported: boolean;
+    readonly smtp: ServerFields;
+}
+/** `undefined` when the account has neither an IMAP nor an SMTP server. */
+export declare function mailSettingsFrom(fields: MailFields): MailSettings | undefined;
+/** The services an account is set up for and the user has not switched off. */
+export declare function enabledServices(present: Readonly<Record<AccountService, boolean>>, disabled: Readonly<Record<AccountService, boolean>>): AccountService[];
+/**
+ * The secret ids to try, in order. The store keeps the IMAP and the SMTP password under
+ * their own ids; the bare ids are what older account types used. SMTP falls back to the
+ * IMAP password because one login often serves both and the store keeps it once.
+ */
+export declare function passwordIds(purpose: CredentialPurpose): readonly string[];

package/lib/types/mapping.spec.d.ts

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

package/lib/types/no-account-store.d.ts

@@ -0,0 +1,4 @@
+import type { SystemAccounts, Unavailable } from './types.js';
+/** The answer of a host with no account store: nothing is listed, every question gets a reason. */
+export declare const noAccountStore: SystemAccounts;
+export declare function isUnavailable<T extends object>(answer: T | Unavailable): answer is Unavailable;

package/lib/types/no-account-store.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/lib/types/types.d.ts

@@ -0,0 +1,78 @@
+export type AccountService = 'mail' | 'calendar' | 'contacts' | 'files';
+/** Which login a credential is for. IMAP and SMTP can hold different secrets. */
+export type CredentialPurpose = 'imap' | 'smtp';
+export type CredentialKind = 'password' | 'oauth2';
+/** `tls` is TLS from the first byte, `starttls` upgrades a plain connection, `none` stays plain. */
+export type ConnectionSecurity = 'tls' | 'starttls' | 'none';
+export interface Account {
+    /** Stable for one account on one host; opaque to the caller. */
+    readonly id: string;
+    /** The store's provider key, e.g. `google` or `imap_smtp`. For display and diagnostics, not for branching. */
+    readonly provider: string;
+    readonly providerName: string;
+    /** What the user logs in as, usually the mail address. */
+    readonly identity: string;
+    /** The name the system shows for the account. */
+    readonly label: string;
+    /** The services the account is set up for AND the user has not switched off. */
+    readonly services: readonly AccountService[];
+}
+export interface ServerSettings {
+    readonly host: string;
+    readonly port: number;
+    readonly security: ConnectionSecurity;
+    /** Absent when the server takes no login (an SMTP relay without authentication). */
+    readonly username?: string;
+}
+export interface MailSettings {
+    readonly sender: {
+        readonly address: string;
+        readonly name?: string;
+    };
+    /** Absent when the account has no IMAP server configured. */
+    readonly imap?: ServerSettings;
+    /** Absent when the account has no SMTP server configured. */
+    readonly smtp?: ServerSettings;
+}
+export interface PasswordCredentials {
+    readonly kind: 'password';
+    readonly secret: string;
+}
+export interface OAuth2Credentials {
+    readonly kind: 'oauth2';
+    /** An access token, valid until `expiresAt`. Ask again afterwards; never store it. */
+    readonly token: string;
+    /** Milliseconds since the epoch. */
+    readonly expiresAt: number;
+}
+/**
+ * Why a question got no answer. A missing capability is a value, never an exception
+ * (ADR 0095), so callers branch on this instead of wrapping every call in try/catch.
+ */
+export type UnavailableReason = 
+/** The host has no account store, or it cannot be reached. */
+'no-account-store' | 'unknown-account'
+/** The account exists but is not set up for what was asked, e.g. no mail server. */
+ | 'not-supported'
+/** The store would not hand the secret out: locked, cancelled, or none stored. */
+ | 'credentials-unavailable';
+export interface Unavailable {
+    readonly kind: 'unavailable';
+    readonly reason: UnavailableReason;
+}
+export type Credentials = PasswordCredentials | OAuth2Credentials | Unavailable;
+export interface AccountCapabilities {
+    /** Services `listAccounts` can report. Empty: this host has no account store. */
+    readonly services: readonly AccountService[];
+    /** Credential kinds `getCredentials` can hand out. Empty: accounts are listed but no secret is given. */
+    readonly credentials: readonly CredentialKind[];
+}
+export interface SystemAccounts {
+    /** What THIS host can answer. Synchronous and cheap: decided when the driver is created. */
+    capabilities(): AccountCapabilities;
+    /** Accounts, optionally only those set up for `service`. Empty when the store cannot be reached. */
+    listAccounts(service?: AccountService): Promise<Account[]>;
+    getMailSettings(account: Account): Promise<MailSettings | Unavailable>;
+    /** The caller owns the result: it is never logged, cached or put in an error by this package. */
+    getCredentials(account: Account, purpose: CredentialPurpose): Promise<Credentials>;
+}

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.56.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.56.0",
+        "@gjsify/unit": "^0.56.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."
+        }
+    }
+}