Files
qbit-printing/src/main/java/com/kingsrook/qbits/printing/PrintingControlAuthorization.java
T
james.maesandClaude Fable 5.2 254f6fd918
maven / build (push) Successful in 7m38s
build / maven (push) Successful in 7m38s
feat(station): a print station authenticates as its own identity
A print station is a computer beside a printer with nobody signed in. Until
now it ran under the session of the person who paired it and renewed that
session every five minutes. A host that ends sessions after user inactivity
would sign it out 15 minutes after every sign-in, and a named person's
session running unattended is hard to defend.

- printing_station: a permission that alone opens nothing. On the device
  routes, after the request proves the one device bound to the station's
  identity, the station may heartbeat, report printers, claim, download and
  acknowledge its own jobs and answer control commands. The proof lives in
  the request's QContext, tied to that session object, never on the session.
  Every row read must belong to that device. Processes and the
  administrative, operator and generic table routes stay closed.
- printingEnrollStation creates a one-use, 15-minute station code.
  POST /qqq/v1/qbit/printing/stations/enroll redeems it with no session and
  answers once with the device proof and the identity's credential. A station
  code cannot pair a person and a person's code cannot create a station.
- PrintingStationIdentities (issue, revoke) is the host's issuer, set with
  PrintingService.withStationIdentities. Without it there is no station
  enrollment (503). An identity issued for an enrollment that then fails is
  revoked. Revoking or removing a station's device revokes its identity; a
  provider failure answers 502 and the action can be repeated.
- The realtime upgrade accepts exactly one credential: a session cookie, or,
  for a station only, a bearer token, verified again on every frame.
- Two additive nullable columns: printing_enrollment.station_name and
  printing_device.station_name. Extension 2.5.0; wire v1 and the subprotocol
  are unchanged, and existing pairings behave as before.

The claim and acknowledgement rules of realtime printing on several nodes are
untouched. docs/STATION-IDENTITY.md describes the flow, the guarantees, the
host contract, what the host, the identity QBit, the provider and the Windows
client still need, the release order and the first enrollment on dev.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 17:55:30 -06:00

197 lines
7.8 KiB
Java

/*
* QQQ - Low-code Application Framework for Engineers.
* Copyright (C) 2021-2025. Kingsrook, LLC
* 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
* contact@kingsrook.com
* https://github.com/Kingsrook/
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.kingsrook.qbits.printing;
import java.util.Set;
import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
import com.kingsrook.qqq.backend.core.context.QContext;
import com.kingsrook.qqq.backend.core.exceptions.QAuthenticationException;
import com.kingsrook.qqq.backend.core.exceptions.QException;
import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryOutput;
import com.kingsrook.qqq.backend.core.model.data.QRecord;
import org.json.JSONObject;
/** Common current-user authorization for native UI and semantic API management. */
public final class PrintingControlAuthorization
{
/** Static authorization facade. */
private PrintingControlAuthorization()
{
}
/** Core user references, never emails or request-body identity, determine attribution. */
public static String principal() throws QException
{
if(QContext.getQSession() == null || QContext.getQSession().getUser() == null
|| QContext.getQSession().getUser().getIdReference() == null || QContext.getQSession().getUser().getIdReference().isBlank())
{
throw new QAuthenticationException("Sign in to continue");
}
// A print station is admitted only inside a request that proved its own device; everywhere else the administrator rule stands.
if(PrintingStationAuthorization.provedDevice() == null)
{
new PrintingAdminPermission().checkPermissionsThrowing(new RunBackendStepInput(), null);
}
PrintingProcesses.currentService();
return QContext.getQSession().getUser().getIdReference();
}
/** Native GetAction applies table access, field protection, and current record security. */
public static QRecord record(String table, String id) throws QException
{
principal();
if(id == null || id.isBlank())
{
throw new QPermissionDeniedException("Record is not accessible");
}
GetInput input = new GetInput();
input.setTableName(table);
input.setPrimaryKey(id);
input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
QRecord row = new GetAction().execute(input).getRecord();
if(row == null)
{
throw new QPermissionDeniedException("Record is not accessible");
}
PrintingStationAuthorization.requireOwn(table, row);
return row;
}
/** Operations without an existing row still require native table read authority. */
public static void table(String table) throws QException
{
principal();
query(new QueryInput().withTableName(table).withFilter(new QQueryFilter().withLimit(1)));
}
/** Explicit enforcement remains effective inside native process action scopes. */
static QueryOutput query(QueryInput input) throws QException
{
input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
return new QueryAction().execute(input);
}
/** A job operation must also authorize its device and exact printer record. */
public static QRecord job(String deviceId, String jobId) throws QException
{
QRecord row = record(PrintingTables.JOB, jobId);
if(!deviceId.equals(row.getValueString("device_id")))
{
throw new QPermissionDeniedException("Job is not assigned to this device");
}
record(PrintingTables.DEVICE, deviceId);
QRecord printer = record(PrintingTables.PRINTER, row.getValueString("printer_row_id"));
if(!deviceId.equals(printer.getValueString("device_id")))
{
throw new QPermissionDeniedException("Printer is not assigned to this device");
}
return row;
}
/** The native process permission remains the domain write authority; generic table writes stay disabled. */
public static void process(String name) throws QException
{
if(PrintingStationAuthorization.isStation())
{
throw new QPermissionDeniedException("A print station cannot run printing management actions");
}
principal();
PermissionsHelper.checkProcessPermissionThrowing(new RunBackendStepInput().withProcessName(name), name);
}
/** Current users can manage authorized devices without impersonating the enrolled agent owner. */
public static JSONObject deviceAction(String deviceId, JSONObject request) throws Exception
{
String actor = principal();
record(PrintingTables.DEVICE, deviceId);
PrintingDeviceProcesses.Action selected = null;
for(PrintingDeviceProcesses.Action action : PrintingDeviceProcesses.Action.values())
{
// The first action owning a wire value is its control process; Remove device reuses REVOKE's wire without owning it.
if(selected == null && action.wire.equals(request.optString("action")))
{
selected = action;
}
}
if(selected == null)
{
throw new PrintingException(400, "Invalid device action");
}
process(selected.process);
PrintingService service = PrintingProcesses.currentService();
String existing = service.existingDeviceAction(deviceId, request.optString("requestId"));
if(existing != null)
{
QRecord receipt = record(PrintingTables.COMMAND, existing);
if(receipt.getValueString("job_id") != null)
{
job(deviceId, receipt.getValueString("job_id"));
}
return service.deviceAction(deviceId, request, actor);
}
Set<String> queue = null;
if("CLEAR_QUEUE".equals(selected.wire))
{
queue = service.queuedJobIdsForControl(deviceId);
Set<String> printers = new java.util.HashSet<>();
for(String id : queue)
{
QRecord queued = record(PrintingTables.JOB, id);
if(!deviceId.equals(queued.getValueString("device_id")))
{
throw new QPermissionDeniedException("Job is not assigned to this device");
}
printers.add(queued.getValueString("printer_row_id"));
}
for(String printerId : printers)
{
QRecord printer = record(PrintingTables.PRINTER, printerId);
if(!deviceId.equals(printer.getValueString("device_id")))
{
throw new QPermissionDeniedException("Printer is not assigned to this device");
}
}
}
if("CANCEL_SPOOL".equals(selected.wire))
{
job(deviceId, request.optString("jobId"));
}
return service.deviceAction(deviceId, request, actor, queue);
}
}