work in progress

This commit is contained in:
2026-08-16 22:00:08 +02:00
parent a914ef1ec4
commit 3c11a88a33
60 changed files with 4487 additions and 41 deletions
+65
View File
@@ -0,0 +1,65 @@
{
"name": "locqr-sdk",
"version": "0.1.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "locqr-sdk",
"version": "0.1.0",
"devDependencies": {
"@types/chrome": "^0.0.280",
"typescript": "^5.6.0"
}
},
"node_modules/@types/chrome": {
"version": "0.0.280",
"resolved": "https://registry.npmjs.org/@types/chrome/-/chrome-0.0.280.tgz",
"integrity": "sha512-AotSmZrL9bcZDDmSI1D9dE7PGbhOur5L0cKxXd7IqbVizQWCY4gcvupPUVsQ4FfDj3V2tt/iOpomT9EY0s+w1g==",
"dev": true,
"license": "MIT",
"dependencies": {
"@types/filesystem": "*",
"@types/har-format": "*"
}
},
"node_modules/@types/filesystem": {
"version": "0.0.36",
"resolved": "https://registry.npmjs.org/@types/filesystem/-/filesystem-0.0.36.tgz",
"integrity": "sha512-vPDXOZuannb9FZdxgHnqSwAG/jvdGM8Wq+6N4D/d80z+D4HWH+bItqsZaVRQykAn6WEVeEkLm2oQigyHtgb0RA==",
"dev": true,
"license": "MIT",
"dependencies": {
"@types/filewriter": "*"
}
},
"node_modules/@types/filewriter": {
"version": "0.0.33",
"resolved": "https://registry.npmjs.org/@types/filewriter/-/filewriter-0.0.33.tgz",
"integrity": "sha512-xFU8ZXTw4gd358lb2jw25nxY9QAgqn2+bKKjKOYfNCzN4DKCFetK7sPtrlpg66Ywe3vWY9FNxprZawAh9wfJ3g==",
"dev": true,
"license": "MIT"
},
"node_modules/@types/har-format": {
"version": "1.2.16",
"resolved": "https://registry.npmjs.org/@types/har-format/-/har-format-1.2.16.tgz",
"integrity": "sha512-fluxdy7ryD3MV6h8pTfTYpy/xQzCFC7m89nOH9y94cNqJ1mDIDPut7MnRHI3F6qRmh/cT2fUjG1MLdCNb4hE9A==",
"dev": true,
"license": "MIT"
},
"node_modules/typescript": {
"version": "5.9.3",
"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
"integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
"dev": true,
"license": "Apache-2.0",
"bin": {
"tsc": "bin/tsc",
"tsserver": "bin/tsserver"
},
"engines": {
"node": ">=14.17"
}
}
}
}
+15
View File
@@ -0,0 +1,15 @@
{
"name": "locqr-sdk",
"private": true,
"version": "0.1.0",
"description": "LOCQR JS SDK — thin bridge between a website and the extension's Port. See sdk/claude.md.",
"type": "module",
"scripts": {
"build": "tsc"
},
"dependencies": {},
"devDependencies": {
"@types/chrome": "^0.0.280",
"typescript": "^5.6.0"
}
}
+180
View File
@@ -0,0 +1,180 @@
// LOCQR JS SDK — a thin bridge, per sdk/claude.md: "no logic of its own,"
// no cryptography, no state beyond the Port connection itself. Wraps
// chrome.runtime.connect(extensionId) — the Port protocol is normative in
// interfaces.md; this file only translates it into locqr.init()/ready/
// requestCredential()/on()/off().
export type LocqrErrorCode = 'NOT_INSTALLED' | 'NOT_REGISTERED' | 'CERT_INVALID' | 'ACCOUNT_ERROR' | 'RUN_FAILED';
export interface LocqrError {
code: LocqrErrorCode;
reason?: string;
security?: boolean;
}
export interface InitOptions {
cert: string;
/** Required for real external-page connections in practice — the dev
* build's extension ID is not the same as the Store-published one
* (sdk/claude.md, "Extension ID in development"). */
extensionId?: string;
}
interface ReadyPayload {
features: string[];
}
export interface Credential {
username: string;
password: string;
}
interface EventPayloads {
ready: ReadyPayload;
'run:started': Record<string, never>;
'run:delivered': { credential: Credential };
'run:error': { error: LocqrError };
}
type LocqrEvent = keyof EventPayloads;
type EventHandler<E extends LocqrEvent = LocqrEvent> = (payload: EventPayloads[E]) => void;
interface VerificationValidMessage {
type: 'verification';
status: 'valid';
features: string[];
}
interface VerificationErrorMessage {
type: 'verification';
status: 'error';
error: LocqrError;
}
interface RunStartedMessage {
type: 'run_started';
}
interface RunDeliveredMessage {
type: 'run_delivered';
credential: Credential;
}
interface RunErrorMessage {
type: 'run_error';
error: LocqrError;
}
type ExtensionMessage = VerificationValidMessage | VerificationErrorMessage | RunStartedMessage | RunDeliveredMessage | RunErrorMessage;
function notInstalled(): Promise<never> {
return Promise.reject<never>({ code: 'NOT_INSTALLED' } satisfies LocqrError);
}
class Locqr {
private port: chrome.runtime.Port | null = null;
private readyPromise: Promise<ReadyPayload> = notInstalled();
private readonly handlers = new Map<LocqrEvent, Set<EventHandler>>();
private settled = false;
// requestCredential()'s pending settlers — one run at a time, per sdk/claude.md
// (mixing the Promise and event models on the same run is not supported;
// this SDK stays a thin bridge and doesn't police that, it just tracks
// the single in-flight requestCredential() call if there is one).
private runResolvers: { resolve: (credential: Credential) => void; reject: (error: LocqrError) => void } | null = null;
init(options: InitOptions): void {
this.settled = false;
if (typeof chrome === 'undefined' || !chrome.runtime?.connect) {
// NOT_INSTALLED is produced locally — it never arrives over the wire
// (interfaces.md, Port message protocol).
this.readyPromise = notInstalled();
this.readyPromise.catch(() => {});
return;
}
this.readyPromise = new Promise<ReadyPayload>((resolve, reject) => {
const settle = (fn: () => void) => {
if (this.settled) return;
this.settled = true;
fn();
};
try {
this.port = options.extensionId ? chrome.runtime.connect(options.extensionId) : chrome.runtime.connect();
} catch {
settle(() => reject({ code: 'NOT_INSTALLED' } satisfies LocqrError));
return;
}
this.port.onDisconnect.addListener(() => {
// Disconnected before a verification response ever arrived —
// the extension isn't there to talk to.
settle(() => reject({ code: 'NOT_INSTALLED' } satisfies LocqrError));
// A disconnect mid-run (e.g. the extension's service worker
// was torn down) also ends any in-flight requestCredential().
this.runResolvers?.reject({ code: 'RUN_FAILED', reason: 'backend_unreachable' });
this.runResolvers = null;
});
this.port.onMessage.addListener((message: ExtensionMessage) => {
switch (message.type) {
case 'verification':
if (message.status === 'valid') {
const payload: ReadyPayload = { features: message.features };
this.emit('ready', payload);
settle(() => resolve(payload));
} else {
settle(() => reject(message.error));
}
return;
case 'run_started':
this.emit('run:started', {});
return;
case 'run_delivered':
this.emit('run:delivered', { credential: message.credential });
this.runResolvers?.resolve(message.credential);
this.runResolvers = null;
return;
case 'run_error':
this.emit('run:error', { error: message.error });
this.runResolvers?.reject(message.error);
this.runResolvers = null;
return;
}
});
this.port.postMessage({ type: 'init', cert: options.cert });
});
this.readyPromise.catch(() => {}); // consumer awaits `ready` on their own schedule
}
get ready(): Promise<ReadyPayload> {
return this.readyPromise;
}
/** Triggers Phase 1. Resolves with the credential at the end of Phase 4, rejects on run_error. */
requestCredential(): Promise<Credential> {
if (!this.port) {
return Promise.reject<Credential>({ code: 'NOT_INSTALLED' } satisfies LocqrError);
}
const port = this.port;
return new Promise<Credential>((resolve, reject) => {
this.runResolvers = { resolve, reject };
port.postMessage({ type: 'request_credential' });
});
}
on<E extends LocqrEvent>(event: E, handler: EventHandler<E>): void {
if (!this.handlers.has(event)) this.handlers.set(event, new Set());
this.handlers.get(event)!.add(handler as EventHandler);
}
off<E extends LocqrEvent>(event: E, handler: EventHandler<E>): void {
this.handlers.get(event)?.delete(handler as EventHandler);
}
private emit<E extends LocqrEvent>(event: E, payload: EventPayloads[E]): void {
for (const handler of this.handlers.get(event) ?? []) {
handler(payload);
}
}
}
const locqr = new Locqr();
export default locqr;
+13
View File
@@ -0,0 +1,13 @@
{
"compilerOptions": {
"target": "ES2022",
"lib": ["ES2022", "DOM"],
"module": "ES2022",
"moduleResolution": "Bundler",
"strict": true,
"types": ["chrome"],
"outDir": "dist",
"declaration": true
},
"include": ["src"]
}