Stax Digital Garden

EMB-1002 - Explicit Access Channels - Passwords and PINs for Guest Sessions

3 min read

Living Document Notice
Published 2026-09-11. The evolving architecture and connected notes for this dispatch live in the Stax Digital Garden.

Explicit Access Channels - Passwords and PINs for Guest Sessions

Explicit Access Channels - Passwords and PINs for Guest Sessions: Warm sepia-white phosphor P4/P20 vector CRT macro depicting a cryptographic PIN challenge keyway matrix and expiring circular guest session gauge

Mainstream cloud photo platforms rely heavily on unauthenticated bearer URLs for album sharing. Anyone possessing the query string link can view and download the entire album contents without authentication challenges. If a link leaks into an indexer, public discord channel, or browser extension history, the private album is effectively public.

Embers eliminates public bearer URLs entirely. Every access channel requires explicit identity assertion. For non-account guests—such as extended family visiting for an event—Embers issues scoped, PIN-protected guest sessions backed by time-bounded cryptographic tokens.

The Dual-Channel Access Model

Access to household media libraries falls into two distinct operational modes:

  1. Circle Members: Authenticated via Argon2id hashed credentials, granting full library visibility and media upload privileges across authorized albums.
  2. Guest Sessions: Authenticated via short numeric PINs or passphrase challenges paired with an album identifier, granting read-only streaming rights for a bounded duration.
interface GuestAccessContract {
  albumId: string;
  pinHash: string; // Argon2id hash of the 6-digit access PIN
  allowedOrigins: string[];
  expiresAt: number; // Unix epoch timestamp
  maxConcurrentStreams: number;
}

The database stores only the one-way Argon2id hash of the guest PIN. When a guest enters their PIN at the shared portal URL, the server verifies the hash, generates an ephemeral JSON Web Token (JWT) scoped strictly to that albumId, and stores the session identifier in an active SQLite session cache table.

Cryptographic Session Minting

When verifying guest challenges, the Node.js backend enforces strict rate-limiting per IP address to prevent PIN brute-force enumeration:

import { Request, Response } from 'express';
import argon2 from 'argon2';
import crypto from 'crypto';
import db from '../db';
 
export async function verifyGuestPin(req: Request, res: Response): Promise<Response> {
  const { albumId, pin } = req.body;
  
  if (!albumId || !pin || typeof pin !== 'string') {
    return res.status(400).json({ error: 'Missing album or access challenge' });
  }
 
  const album = db.prepare(
    'SELECT pin_hash, expires_at FROM guest_shares WHERE album_id = ? AND revoked = 0'
  ).get(albumId) as { pin_hash: string; expires_at: number } | undefined;
 
  if (!album || Date.now() > album.expires_at) {
    return res.status(404).json({ error: 'Share channel expired or not found' });
  }
 
  const isValid = await argon2.verify(album.pin_hash, pin);
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid access challenge' });
  }
 
  const sessionToken = crypto.randomBytes(32).toString('hex');
  const sessionExpiry = Date.now() + 1000 * 60 * 60 * 24; // 24-hour guest window
 
  db.prepare(
    'INSERT INTO active_sessions (token_hash, album_id, role, expires_at) VALUES (?, ?, ?, ?)'
  ).run(
    crypto.createHash('sha256').update(sessionToken).digest('hex'),
    albumId,
    'guest',
    sessionExpiry
  );
 
  return res.status(200).json({ token: sessionToken, expiresIn: sessionExpiry });
}

Because the token hash is verified against the database for every range request, the library host can revoke access instantly from the admin dashboard by setting revoked = 1. Active streams drop connection immediately upon the next segment request.

Architectural Invariant

Embers rejects unauthenticated bearer links. Media access requires an explicit authentication gate backed by local credential verification:

[Media Access Request] -> [Auth Challenge] -> [Verified Session] -> [Direct Storage Read]
  • Directus Target: embers
  • Garden Source Reference: MOC - The Digital Necropolis and Cold Decadal Storage, MOC - Bosun PKM Tools
  • Garden Source Reference: Session Revocation Mechanisms, Cryptographic Guest Tokens

Graph View